Format

LIB$ADAWI add ,sum ,sign

Returns

Arguments

add

The addend operand to be added to the value of sum. The add argument is the address of a signed word that contains the addend operand.

sum

The word to which add is added. The sum argument is the address of a signed word integer containing this value. The add operand is added to the sum operand, and the value of the sum argument is replaced by the result of this addition. The sum argument must be word-aligned; in other words, its address must be a multiple of 2.

sign

Sign of the sum argument. The sign argument is the address of a signed word integer that is assigned the value –1, 0, or 1, depending on whether the new value of sum is negative, 0, or positive.

Description

LIB$ADAWI allows the user to perform an interlocked add operation using an aligned word, and makes the VAX ADAWI instruction available as a callable routine. This routine also enables the user to implement synchronization primitives for multiprocessing. On Alpha systems, OpenVMS Alpha instructions perform the equivalent operation.

The add operation is interlocked against similar operations on other processors in a multiprocessor environment. This provides an atomic addition operation. The destination must be aligned on a word boundary; that is, bit 0 of the address of the sum operand must be 0.

If the addend and the sum operand overlap, the result of the addition, the value of the sign argument, and the associated condition codes are unpredictable.

The value of the sign argument is useful when LIB$ADAWI is used to implement locking in a multiprocessing program. For example, a process that is waiting to seize a lock or a resource calls LIB$ADAWI to add 1 to the sum. When the call returns, the waiting process checks the value of sign.

In this algorithm, if the value of the sign argument is –1, that indicates that the process successfully seized the lock or resource, and other free resources are available. A value of 0 indicates that the process successfully seized the lock or the last available resource. A value of 1 indicates that the process was unable to seize the lock.

It is not sufficient for a waiting process to test the value of sum. The result is unpredictable because other processes can alter the value of sum after the original process executes the ADAWI instruction but before it tests the value of sum. However, a process can safely test the value of sign because its value is determined by the ADAWI instruction and is unaffected by other processes' activities.

Condition Values Returned

Format

LIB$ADDX addend-array ,augend-array ,resultant-array [,array-length]

Returns

Arguments

addend-array

First multiple-precision, signed two’s complement integer that LIB$ADDX adds to the second two’s complement integer. The addend-array argument is the address of the array containing the two’s complement number to be added.

augend-array

Second multiple-precision, signed two’s complement integer that LIB$ADDX adds to the first two’s complement integer. The augend-array argument is the address of the array containing the two’s complement number.

resultant-array

Multiple-precision, signed two’s complement integer result of the addition. The resultant-array argument is the address of the array into which LIB$ADDX writes the result of the addition.

array-length

Length in longwords of the arrays to be operated on; each array is of length array-length. The array-length argument is the address of a signed longword integer containing the length. The array-length argument must not be negative. This is an optional argument. If omitted, the default is 2.

Description

LIB$ADDX adds two signed two's complement integers of arbitrary length. The integers are located in arrays of longwords. The higher addresses of these longwords contain the higher precision parts of the values. The highest- addressed longword contains the sign and 31 bits of precision. The remaining longwords contain 32 bits of precision in each. The number of longwords in each array is specified in the optional argument array-length. The default array length is 2, which corresponds to the OpenVMS quadword data type.

Any two or all three of the first three arguments can be the same.

Condition Value Returned

Example

C+
C This Fortran example program shows the use
C of LIB$ADDX.
C-

        INTEGER
        A(2),B(2),C(2),RETURN
        DATA A/’00000001’x,’7FFF407F’x/
        DATA B/’FFFFFFFF’x,’8000BF80’x/

C+
C The highest addressed longword of "A" is A(2).
C So, "A" represents the integer value (’7FFF407F’x) * 16**7 + 1.
C That is, A(2) is 576447592255193089.
C "B" is the twos complement representation of "-A".
C-

        RETURN
        = LIB$ADDX(A,B,C)
        TYPE *,’Let A = 576447592255193089.’
        TYPE *,’Then A + B is 0.’
        TYPE 1,C(2),C(1)
        1 FORMAT(’ "A" - "A" is ’,1H’,I1,I1,3H’x.)
        TYPE *,’Note that C is C(2) concatenated with C(1).’

C+
C Let "A" have the value 72057594037927937 = ’1000000000000001’x.
C Let "B" have the value 4294967295 = ’00000000FFFFFFFF’x.
C

        A(1) = ’00000001’x
        A(2) = ’10000000’x
        B(1) = ’FFFFFFFF’x
        B(2) = ’00000000’x
C+
C Then "A" + "B" is 72057598332895232.
C-

lib
        RETURN = LIB$ADDX(A,B,C)
        TYPE *,’ ’
        TYPE *,’LET A = 72057594037927937 and B = 4294967295’
        TYPE *,’Then A + B is ’,C
        TYPE 2,C(2),C(1)
2       FORMAT(’ 72057598332895232 is represented as ’,1H’,Z8.8,Z8.8,3H’x.)
        TYPE *,’Recall that 72057598332895232 is C(2) concatenated
      1 with C(1).’
        END

Let A = 576447592255193089.
Then A + B is 0.
"A" - "A" is '00'x.
Note that C is C(2) concatenated with C(1).
LET A = 72057594037927937 and B = 4294967295
Then A + B is            0   268435457
72057598332895232 is represented as '10000001       0'x.
Recall that 72057598332895232 is C(2) concatenated  with C(1).

Format

LIB$ADD_TIMES time1 ,time2 ,resultant-time

Returns

Arguments

time1

First time that LIB$ADD_TIMES adds to the second time. The time1 argument is the address of an unsigned quadword containing the first time to be added. The time1 argument may be either a delta time or an absolute time; however, at least one of the arguments, time1 or time2, must be a delta time.

time2

Second time that LIB$ADD_TIMES adds to the first time. The time2 argument is the address of an unsigned quadword containing the second time to be added. The time2 argument may be either a delta time or an absolute time; however, at least one of the arguments, time1 or time2, must be a delta time.

resultant-time

The result of adding time1 and time2. The resultant-time argument is the address of an unsigned quadword containing the result. If both time1 and time2 are delta times, then resultant-time is a delta time. Otherwise, resultant-time is an absolute time.

Description

LIB$ADD_TIMES adds two OpenVMS internal times. It can add two delta times or a delta time and an absolute time. LIB$ADD_TIMES cannot add two absolute times.

Condition Values Returned

Format

LIB$ANALYZE_SDESC input-descriptor ,data-length ,data-address

Corresponding JSB Entry Point

LIB$ANALYZE_SDESC_R2

Returns

Arguments

input-descriptor

Input descriptor from which LIB$ANALYZE_SDESC extracts the length of the data and the address at which the data starts. The input-descriptor argument is the address of a descriptor pointing to the input data.

data-length

Length of the data; LIB$ANALYZE_SDESC extracts this length value from the input descriptor. The data-length argument is the address of an unsigned word integer into which LIB$ANALYZE_SDESC writes the length.

data-address

Starting address of the data; LIB$ANALYZE_SDESC extracts this address from the input descriptor. The data-address argument is the address of an unsigned longword into which LIB$ANALYZE_SDESC writes the starting address of the data.

Description

See STR$ANALYZE_SDESC for a similar routine that signals an error rather than returning a status.

Condition Values Returned

Format

LIB$ANALYZE_SDESC_64 input-descriptor ,data-length ,data-address [,descriptor-type]

Corresponding JSB Entry Point

Returns

Arguments

input-descriptor

Input descriptor from which LIB$ANALYZE_SDESC_64 extracts the length of the data and the address at which the data starts. The input-descriptor argument is the address of a descriptor pointing to the input data. The input descriptor can be a longword (unsigned) or a quadword (unsigned).

data-length

Length of the data; LIB$ANALYZE_SDESC_64 extracts this length value from the input descriptor. The data-length argument is the address of an unsigned quadword integer into which LIB$ANALYZE_SDESC_64 writes the length.

data-address

Starting address of the data; LIB$ANALYZE_SDESC_64 extracts this address from the input descriptor. The data-address argument is the address of an unsigned quadword into which LIB$ANALYZE_SDESC_64 writes the starting address of the data.

descriptor-type

Flag value indicating the type of input descriptor. The descriptor-type argument contains the address of an unsigned longword integer to which LIB$ANALYZE_SDESC_64 writes a 0 for a 32-bit input descriptor or a 1 for a 64-bit descriptor.

This argument is optional.

Description

See STR$ANALYZE_SDESC_64 for a similar routine that signals an error rather than returning a status.

Condition Values Returned

Format

LIB$ASN_WTH_MBX device-name [,maximum-message-size] [,buffer-quota] ,device-channel,mailbox-channel

Returns

Arguments

device-name

Device name that LIB$ASN_WTH_MBX passes to the $ASSIGN service. The device-name argument is the address of a descriptor pointing to the device name.

maximum_message_size

Maximum message size that can be sent to the mailbox; LIB$ASN_WTH_MBX passes this argument to the $CREMBX service. The maximum-message-size argument is the address of a signed longword integer containing this maximum message size.

buffer-quota

Number of system dynamic memory bytes that can be used to buffer messages sent to the mailbox; LIB$ASN_WTH_MBX passes this argument to the $CREMBX service. The buffer-quota argument is the address of a signed longword integer containing this buffer quota.

device-channel

Device channel that LIB$ASN_WTH_MBX receives from the $ASSIGN service. The device-channel argument is the address of an unsigned word integer into which $ASSIGN writes the device channel.

mailbox-channel

Mailbox channel that LIB$ASN_WTH_MBX receives from the $CREMBX service. The mailbox-channel argument is the address of an unsigned word integer into which $CREMBX writes the mailbox channel.

Description

A mailbox is a virtual device used for communication between processes. A channel is the communication path that a process uses to perform I/O operations to a particular device. LIB$ASN_WTH_MBX assigns a channel to a device and associates a mailbox with the device. It returns both the device channel and the mailbox channel to the mailbox.

Normally, a process calls the $CREMBX system service to create a mailbox and assign a channel and logical name to it. Any process running in the same job and using the same logical name uses the same mailbox.

LIB$ASN_WTH_MBX associates the physical mailbox name with the channel assigned to the device. To create a temporary mailbox for itself and other processes cooperating with it, your program calls LIB$ASN_WTH_MBX. The Run-Time Library routine assigns the channel and creates the temporary mailbox by using the system services $GETDVIW, $ASSIGN, and $CREMBX. Instead of a logical name, the mailbox is identified by a physical device name of the form MBcu. The physical device name MBcu is made up of the following elements:

The routine returns the channel for this device name to the calling program, which then must pass the mailbox channel to the other programs with which it cooperates. In this way, the cooperating processes access the mailbox by its physical name, instead of by a logical name.

The calling program passes the routine a device name, which specifies the device to which the channel is to be assigned. For this argument (called device-name), you may use a logical name. If you do so, the routine attempts one level of logical name translation.

The privilege restrictions and process quotas required for using this routine are those required by the $GETDVIW, $CREMBX, and $ASSIGN system services.

Condition Values Returned

Any condition value returned by the called system services $ASSIGN, $CREMBX, $GETDVI, or the RTL routines LIB$GET_EF and LIB$FREE_EF.

Format

LIB$AST_IN_PROG

Returns

Truth value that indicates whether an AST is currently in progress (value = 1) or not (value = 0).

Arguments

None.

Description

An asynchronous system trap (AST) is an OpenVMS mechanism for providing a software interrupt when an external event occurs, such as the user pressing Ctrl/C. When an external event occurs, the OpenVMS operating system interrupts the execution of the current process and calls a routine that you supply. While that routine is active, the AST is said to be in progress, and the process is said to be executing at AST level. When your AST routine returns control to the original process, the AST is no longer active, and execution continues where it left off.

LIB$AST_IN_PROG indicates to the calling program whether an AST is currently in progress. Your program can call LIB$AST_IN_PROG to determine whether it is executing at AST level and then take appropriate action. This routine is useful if you are writing AST-reentrant code, which takes different actions depending on whether an AST is in progress. For example, the routine might have two separate statically allocated storage areas, one for AST level and one for non-AST level.

LIB$AST_IN_PROG calls the RTL routines LIB$FREE_EF and LIB$GET_EF, and the $GETJPI system service. If LIB$AST_IN_PROG or any of these routines encounters an error, LIB$AST_IN_PROG calls LIB$STOP.

Condition Values Returned

None.

Example

PROGRAM AST_IN_PROGRESS(INPUT, OUTPUT);
FUNCTION LIB$AST_IN_PROG : INTEGER; EXTERN;
VAR
  ASTVALUE : INTEGER;
BEGIN
  ASTVALUE := LIB$AST_IN_PROG;
  CASE ASTVALUE OF
    0 :   WRITELN(’AN AST IS NOT IN PROGRESS’);
     1   :  WRITELN(’AN AST IS IN PROGRESS’);
  END { of the case statement }
END.

This Pascal program determines whether or not an AST is in progress.

Format

LIB$ATTACH process-id

Returns

Argument

process-id

Identification of the process to which LIB$ATTACH requests the calling process to attach its terminal. The process-id argument is the address of an unsigned longword integer containing the process identification. The specified process must be currently detached (by means of a SPAWN or ATTACH command or by a call to LIB$SPAWN or LIB$ATTACH) and must be part of the caller’s job.

Description

LIB$ATTACH requests the calling process's command language interpreter (CLI) to detach the terminal of the calling process and reattach it to a different process. The calling process then hibernates. LIB$ATTACH provides the same function as the DCL command ATTACH. For more information on ATTACH, see the VSI OpenVMS DCL Dictionary.

LIB$ATTACH is supported for use with the DCL CLI. If used with the Monitor Control Routine (MCR) CLI, the error status LIB$_NOCLI is returned. If an image is run directly as a subprocess or detached process, no CLI is present to perform this function. In such cases, the error status LIB$_NOCLI is returned.

Condition Values Returned

Format

LIB$BBCCI position ,bit-zero-address

Returns

State of the bit before it was cleared by LIB$BBCCI: 1 if the bit was previously set, and 0 if the bit was previously clear.

Arguments

position

Bit position, relative to bit-zero-address, of the bit that LIB$BBCCI tests and clears. The position argument is the address of a signed longword integer containing the bit position. A position of zero denotes the low-order bit of the byte base. The bit position is equal to the offset of the bit chosen from the base position. This offset may span the entire range of a signed longword integer; negative offsets access bits in lower addressed bytes.

bit-zero-address

Address of the byte containing bit 0 of the field that LIB$BBCCI references. The bit-zero-address argument is the location of the base position. The bit that LIB$BBCCI tests and clears is position bits offset from the low bit of bit-zero-address.

Description

The single bit specified by position and bit-zero-address is tested, the previous state of the bit remembered, and the bit cleared. The reading of the state of the bit and its clearing are interlocked against similar operations by other processors or devices in the system. The remembered previous state of the bit is then returned as the function value of LIB$BBCCI.

Condition Values Returned

None.

Example

C+
C This Fortran program demonstrates the use of
C LIB$BBCCI.
C-
        INTEGER*4 STATES(4)        ! 128 shared state bits
        COMMON /STATES/ STATES     ! Could be shared memory
        LOGICAL*4 LIB$BBCCI
        IF (LIB$BBCCI (42, STATES)) THEN
            TYPE *,’State bit 42 was set’
        ELSE
            TYPE *,’State bit 42 was clear’
        END IF
        END

This Fortran example tests and clears bit 42 of array STATES, which is in a COMMON area (possibly shared between two processors).

The output generated by this program is as follows:

$ RUN STATE
State bit 42 was clear.

Format

LIB$BBSSI position ,bit-zero-address

Returns

The state of the bit before it was set by LIB$BBSSI: 1 if it was previously set, and 0 if it was previously clear.

Arguments

position

Bit position, relative to bit-zero-address, of the bit that LIB$BBSSI tests and sets. The position argument is the address of a signed longword integer containing the bit position. A position of zero denotes the low-order bit of the byte base. The bit position is equal to the offset of the bit chosen from the base position. This offset may span the entire range of a signed longword integer; negative offsets access bits in lower addressed bytes.

bit-zero-address

Address of the byte containing bit 0 of the field that LIB$BBSSI references. The bit-zero-address argument is the location of the base position. The bit that LIB$BBSSI tests and sets is position bits offset from the low bit of bit-zero-address.

Description

The single bit specified by position and bit-zero-address arguments is tested, the previous state of the bit remembered, and the bit set. The reading of the state of the bit and its setting are interlocked against similar operations by other processors or devices in the system. The remembered previous state of the bit is then returned as the function value of LIB$BBSSI.

Condition Values Returned

None.

Example

C+
C This Fortran example program demonstrates
C the use of LIB$BBSSI.
C-

      INTEGER*4 STATES(4)       ! 128 shared state bits
      COMMON /STATES/ STATES    ! Could be shared memory
      LOGICAL*4 LIB$BBSSI
      IF (LIB$BBSSI (104, STATES)) THEN
       TYPE *,’State bit 104 was set’
      ELSE
       TYPE *,’State bit 104 was clear’
      END IF
      END

This Fortran example tests and sets bit 104 of array STATES, which is in a COMMON storage area (possibly shared between two processors).

$ RUN STATEB
State bit 104 was clear.

Format

LIB$BUILD_NODESPEC primary-nodename, nodespec [,acs] [,secondary-nodename] [,nodespec-length]

Returns

Arguments

primary-nodename

Primary node name. The primary-nodename argument contains the address of a descriptor pointing to this node-name string. The primary node name should not contain unnecessary quotation marks (that is, quotation marks (" ") that are not part of a simple name within the node name).

The error LIB$_INVARG is returned if primary-nodename points to a null string. The error LIB$_INVSTRDES is returned if primary-nodename is an invalid descriptor.

nodespec

Node-name specification. The nodespec argument contains the address of a descriptor pointing to this output node-name specification string. LIB$BUILD_ NODESPEC writes the output node-name specification into the buffer pointed to by the nodespec descriptor.

The error LIB$_INVSTRDES is returned if nodespec is an invalid descriptor.

The length field of the nodespec descriptor is not updated unless nodespec is a dynamic descriptor with a length less than the resultant node-name specification. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.

The nodespec argument contains an unusable result when LIB$BUILD_NODESPEC returns in error.

acs

Access control string. The acs argument contains the address of a descriptor pointing to this access control string. The access control string must be a quoted string.

The error LIB$_INVSTRDES is returned if acs is an invalid descriptor.

secondary-nodename

Secondary node name. The secondary-nodename argument contains the address of a descriptor pointing to this secondary node-name string.

The error LIB$_INVSTRDES is returned if secondary-nodename is an invalid descriptor.

nodespec-length

Length of the output node-name specification. The nodespec-length argument is the address of an unsigned word that contains this length in bytes.

The nodespec-length argument contains an unusable result when LIB$BUILD_ NODESPEC returns in error.

Description

This routine builds the parsable form of a node name as the output node-name specification from the network usable form. Refer to LIB$GET_HOSTNAME for the definitions of both the parsable form and the network usable form.

The network usable form is specified by the argument primary-nodename. If primary-nodename contains special characters, it is enclosed in quotation marks (" ") to build the node-name specification. The quotation marks prevent the special characters from being recognized as terminator characters and enables correct parsing of the node-name syntax.

If you enclose primary-nodename in quotation marks, any quotation marks that are part of any simple names within primary-nodename are doubled (that is, each quotation mark (") is turned into two quotation marks ( ")). LIB$BUILD_NODESPEC checks if the fully quoted primary node name exceeds 1024 characters. The error condition LIB$_NODTOOLNG is returned if this is the case.

To form the output node-name specification, the fully quoted primary node name is concatenated with the access control string (if supplied) and the double colons and is followed by the secondary node name (if supplied).

This routine does not validate any of the input arguments to ensure they can form a syntactically valid node name when they are concatenated.

If the routine overflows the output buffer pointed to by nodespec, the output node-name specification is truncated, and the alternate successful status LIB$_STRTRU is returned.

The nodespec-length argument, if supplied, is always set to the length of the node-name specification that is written into the output buffer pointed to by nodespec.

Condition Value Returns

Any condition value returned by LIB$SCOPY_DXDX.

Format

LIB$CALLG argument-list ,user-procedure

Returns

Return value, if any, of the called routine, unchanged by LIB$CALLG.

Arguments

argument-list

Argument list to be passed to user-procedure. The argument-list argument is the address of an array of longwords that is the argument list. The first longword contains the count of the remaining longwords, to a maximum of 255.

user-procedure

Routine that LIB$CALLG calls with the specified argument list.

Description

LIB$CALLG is used to call routines that accept variable-length argument lists when the number of arguments to be passed is not known until execution time. LIB$CALLG is also used to call such routines from strongly typed languages, which require routines to be declared as having a fixed number of arguments.

Condition Values Returned

None.

Format

LIB$CALLG_64 argument-list ,user-procedure

Returns

Return value, if any, of the called routine, unchanged by LIB$CALLG_64.

Arguments

argument-list

Argument list to be passed to user-procedure. The argument-list argument is the address of an array of quadwords that is the argument list. The first quadword contains the count of the remaining quadwords, to a maximum of 255.

user-procedure

Routine that LIB$CALLG_64 calls with the specified argument list.

Description

LIB$CALLG_64 is useful for calling routines that accept variable-length argument lists when the number of arguments to be passed is not known until execution time. LIB$CALLG_64 can also be used to call such routines from strongly typed languages, which require routines to be declared as having a fixed number of arguments.

Condition Values Returned

None.

Format

LIB$CHAR one-character-string ,ascii-code

Returns

Arguments

one-character-string

ASCII character string consisting of a single character followed by trailing spaces, if needed, that LIB$CHAR creates when it transforms the ASCII character code. The one-character-string argument is the address of a descriptor pointing to the character string that LIB$CHAR writes.

ascii-code

Single 8-bit ASCII character code that LIB$CHAR transforms to an ASCII string. The ascii-code argument is the address of an unsigned byte containing the ASCII character code.

Description

LIB$CHAR is the inverse of LIB$ICHAR. (See the description of LIB$ICHAR.) LIB$CHAR is not a binary-to-ASCII conversion routine. LIB$CHAR merely interprets ascii-code as an ASCII character code and converts it to a string.

Condition Values Returned

Format

LIB$COMPARE_NODENAME nodename1 ,nodename2 ,comparison-result

Returns

Arguments

nodename1

First node name to be compared. The nodename1 argument contains the address of a descriptor pointing to this node-name string.

The error LIB$_INVARG is returned if nodename1 contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if nodename1 is an invalid descriptor.

nodename2

Second node name to be compared. The nodename2 argument contains the address of a descriptor pointing to this node-name string.

The error LIB$_INVARG is returned if nodename2 contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if nodename2 is an invalid descriptor.

comparison-result

Result of the comparison. The comparison-result argument is the address of an unsigned longword that contains the comparison result. If the two node names are equal, 0 is returned. If they are not equal, 1 is returned.

Comparison-result contains an unusable result when LIB$COMPARE_ NODENAME returns in error.

Description

Condition Values Returned

Any condition value returned by RTL routine LIB$SCOPY_R_DX or by the $IPC DECnet service.

Format

LIB$COMPRESS_NODENAME nodename ,compressed-nodename [,resultant-length]

Returns

Arguments

nodename

Node name to be compressed. The nodename argument contains the address of a descriptor pointing to this node-name string.

The error LIB$_INVARG is returned if nodename contains an invalid node name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if the nodename descriptor is invalid.

compressed-nodename

Compressed node name. The compressed-nodename argument contains the address of a descriptor pointing to the compressed node-name string. LIB$COMPRESS_NODENAME writes the compressed node name into the buffer pointed to by compressed-nodename.

The error LIB$_INVSTRDES is returned if compressed-nodename is an invalid descriptor.

The length field of the compressed-nodename descriptor is not updated unless compressed-nodename is a dynamic descriptor with a length less than the resulting compressed node name. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage.

The compressed-nodename argument contains an unusable result when LIB$COMPRESS_NODENAME returns in error.

resultant-length

Length of the compressed node name. The resultant-length argument is the address of an unsigned word that contains this length in bytes.

The resultant-length argument contains an unusable result when LIB$COMPRESS_NODENAME returns in error.

Description

This routine compresses a given node name to a short form that is usable within the local naming environment in which the compression is performed. The local naming environment is defined by the underlying network directory services. Be careful when using the compressed node name for making network connections. Using the compressed node name outside the intended local naming environment may result in an ambiguous reference. Use the full name whenever you need to eliminate ambiguity.

The nodename argument is validated against the supported form of node names. The error LIB$_INVARG is returned if the input node name is invalid.

When calling LIB$COMPRESS_NODENAME in a DECnet-Plus for OpenVMS environment, the underlying network layer verifies the existence of the input node name. If the input node name does not resolve to an existing node name in the naming environment, an error condition is returned by the underlying network layer and propagated back to the caller of LIB$COMPRESS_NODENAME.

If the returned compressed node name overflows the buffer pointed to by compressed-nodename, the compressed node name is truncated, and the alternate successful status LIB$_STRTRU is returned.

The actual length of the compressed node name written to the output buffer compressed-nodename is returned in resultant-length if this argument is supplied.

In a DECnet environment, compressing a DECnet-Plus node name results in the error condition LIB$_INVARG.

Condition Values Returned

Any condition value returned by RTL routine LIB$SCOPY_R_DX or by the $IPC DECnet service.

Format

LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context] [,flags] [,defaults] [,defaulted-fields]

Returns

Arguments

date-string

Date string that specifies the absolute time to be converted to an internal system time. The date-string argument is the address of a descriptor pointing to this date string. This string must have a format corresponding to the currently defined input format, or it must be one of the relative day strings YESTERDAY, TODAY, or TOMORROW, or their equivalents in the currently selected language.

date-time

Receives the converted time. The date-time argument is the address of an unsigned quadword that contains this OpenVMS internal format converted time.

user-context

Context variable that receives the translation context from a call to LIB$INIT_DATE_TIME_CONTEXT and then retains the translation context over multiple calls to LIB$CONVERT_DATE_STRING. The user-context argument is the address of an unsigned longword that contains this context. The user program should not write directly to this variable once it is initialized.

The user-context parameter is optional. However, if a context cell is not passed, the routine LIB$CONVERT_DATE_STRING may abort if two threads of execution attempt to manipulate the context area concurrently. Therefore, when calling this routine in situations where reentrancy might occur, such as from AST level, VSI recommends that users specify a different context cell for each calling thread.

flags

Specifies which date or time fields of the date-string argument might be omitted so that default values are applied. The flags argument is the address of a longword bit mask that contains these flags. A set bit indicates that the field may be omitted. The bit definitions for the mask correspond to the fields in a $NUMTIM ‘‘timbuf’’ structure as follows:

Bits 7 through 31 must be zero and are reserved for use by VSI. If this parameter is omitted, a default value of 120 (78H) is used, indicating that the time fields may be defaulted but the date fields may not.

defaults

Supplies the defaults to be used for omitted fields. The defaults argument is the address of an array of unsigned words containing these default values. This array corresponds to a 7-word $NUMTIM ‘‘timbuf’’ structure. If the defaults argument is omitted, the following defaults are applied:

defaulted-field

Indicates which date or time fields have been defaulted. The defaulted-fields argument is the address of a longword bit mask that specifies these fields. The bit definitions are identical to those of the flags bit mask. A set bit indicates that the field was defaulted. Bits 7 through 31, which are reserved for use by VSI, are zeroed.

Description

In general, if an application is reading text from internal storage, the language and input format should be specified at compile time. If this is the case, use the routine LIB$INIT_DATE_TIME_CONTEXT to specify the language and input format of your choice.

If an application is accepting text from a user, the logical name method of specifying language and format should be used. In this method, the user assigns equivalence names to the logical names SYS$LANGUAGE and LIB$DT_INPUT_FORMAT, thereby selecting the language and input format of the date and time at run time.

See the VSI OpenVMS Programming Concepts Manual for a description of system date and time operations as well as a detailed description of the format mnemonics used in these routines.

Condition Values Returned

Any condition value returned by RTL routines LIB$GET_VM, LIB$FREE_VM, LIB$FREE1_DD, and LIB$SCOPY_R_DX, and system services $NUMTIM and $GETTIM.

Format

LIB$CRC crc-table ,initial-crc ,stream

Returns

The computed cyclic redundancy check.

Arguments

crc-table

The 16-longword cyclic redundancy check table created by a call to LIB$CRC_ TABLE. The crc-table argument is the address of a signed longword integer containing this table. Because this table is created by LIB$CRC_TABLE and then used as input in LIB$CRC, your program must call LIB$CRC_TABLE before it calls LIB$CRC.

initial-crc

Initial cyclic redundancy check. The initial-crc argument is the address of a signed longword integer containing the initial cyclic redundancy check.

stream

Data stream for which LIB$CRC is calculating the CRC. The stream argument is the address of a descriptor pointing to the data stream.

Description

Before your program can call LIB$CRC, it must call LIB$CRC_TABLE. LIB$CRC_TABLE takes a polynomial as its input and builds the table that LIB$CRC uses to calculate the CRC.

LIB$CRC allows your high-level language program to use the CRC instruction, which calculates the cyclic redundancy check. This instruction checks the integrity of a data stream by comparing its state at the sending point and the receiving point. Each character in the data stream is used to generate a value based on a polynomial. The values for each character are then added together. This operation is performed at both ends of the data transmission, and the two result values compared. If the results disagree, then an error occurred during the transmission.

Condition Values Returned

None.

Example

For an example on how to use LIB$CRC, refer to the BASIC example at the end of the description of LIB$CRC_TABLE

Format

LIB$CRC_TABLE polynomial-coefficient ,crc-table

Returns

None.

Arguments

polynomial-coefficient

A bit mask indicating which polynomial coefficients are to be generated by LIB$CRC_TABLE. The polynomial-coefficient argument is the address of an unsigned longword integer containing this bit mask.

crc-table

The 16-longword table that LIB$CRC_TABLE produces. The crc-table argument is the address of a signed longword integer containing the table.

Description

The table created by LIB$CRC_TABLE can be passed to the LIB$CRC routine for generating the cyclic redundancy check value for a stream of characters.

Condition Values Returned

None.

Example

1   %TITLE "Demonstrate LIB$CRC and LIB$CRC_TABLE"
    %SBTTL "Declarations"
    %IDENT "1-001"

    !--
    OPTION TYPE = EXPLICIT
    DECLARE LONG CRC_TABLE(15), ! CRC table array &
            LONG CRC_VAL_1, ! CRC for first stream &
            LONG CRC_VAL_2, ! CRC for second stream &
            STRING DATA_1, ! First data stream &
           STRING DATA_2 ! Second data stream
    EXTERNAL LONG FUNCTION LIB$CRC ! Rtn to calculate CRC
    EXTERNAL SUB LIB$CRC_TABLE ! Rtn to set up table for CRC

    OPEN "SYS$INPUT:" FOR INPUT AS FILE 1%
    !+
    ! Initialize the CRC table. Use the CRC-16 polynomial (refer to the
    ! VAX Architecture Reference Manual). This is the polynomial used by
    ! DDCMP and Bisync.
    !-

    CALL LIB$CRC_TABLE( O’120001’L, CRC_TABLE() BY REF )
    !+
    ! Get data from user.
    !-

    LINPUT #1%, ’Enter string: ’;DATA_1
    !+
    ! Calc the CRC for the user’s input. This CRC polynomial needs
    ! an initial CRC of 0 (refer to the VAX Architecture Reference Manual).
    ! LIB$CRC returns a longword, but only the low-order word is valid
    ! for this polynomial.
    !-

    CRC_VAL_1 = LIB$CRC( CRC_TABLE() BY REF, 0%, DATA_1 )
    CRC_VAL_1 = CRC_VAL_1 AND 32767%

    !+
    ! Get more data from user.
    !-

    LINPUT #1%, ’Enter a second string: ’;DATA_2
    CRC_VAL_2 = LIB$CRC( CRC_TABLE() BY REF, 0%, DATA_2 )
    CRC_VAL_2 = CRC_VAL_2 AND 32767%

    !+
    ! Tell the user the results of the CRC comparison.
    !-

    IF CRC_VAL_1 = CRC_VAL_2
    THEN
        PRINT "The two CRCs";CRC_VAL_1;" and ";CRC_VAL_2;" were the same"
    ELSE
        PRINT "The two CRCs";CRC_VAL_1;" and ";CRC_VAL_2;" were different"
    END IF

    IF DATA_1 = DATA_2
    THEN
        PRINT "The two strings were the same"
    ELSE
        PRINT "The two strings were different"
    END IF
    END

$ RUN CRC
Enter string:  DOVE
Enter a second string:  HOSE
The two CRCs 29915 and 29915 were the same
The two strings were different

Format

LIB$CREATE_DIR device-directory-spec [,owner-UIC] [,protection-enable] [,protection-value] [,maximum-versions] [,relative-volume-number] [,initial-allocation]

Returns

Arguments

device-directory-spec

Directory specification of the directory or subdirectory that LIB$CREATE_DIR will create. The device-directory-spec argument is the address of a descriptor pointing to this directory specification.

The format of the device-directory-spec string conforms to standard OpenVMS Record Management Services (RMS) format. This specification must contain a directory or subdirectory specification. It may contain a disk specification. SMD$:[THIS.IS.IT] is an example of a standard RMS file specification, where SMD$ is the disk specification and [THIS.IS.IT] is the subdirectory specification.

This specification cannot contain a node name, file name, file type, file version, or wildcard characters. The maximum size of this string is 255 characters on VAX, and 4095 characters on Alpha.

owner-UIC

User identification code (UIC) identifying the owner of the created directory or subdirectory. The owner-UIC argument is the address of an unsigned longword that contains the UIC. If owner-UIC is zero, the owner UIC is that of the parent directory. The specified value for owner-UIC is interpreted as a 32-bit octal number, with two 16-bit fields:

This is an optional argument. The default is the UIC of the current process except when the directory is in UIC format. For a directory in UIC format, for example [123,321], the UIC of the created directory is used.

protection-enable

Mask specifying the bits of protection-value to be set. The protection-enable argument is the address of an unsigned word containing this protection mask.

The figure below shows the structure of a protection mask. Access is allowed for bits set to 0.

Bits set in the protection-enable mask cause corresponding bits of protection-value to be set. Bits not set in the protection-enable mask cause corresponding bits of protection-value to take the value of the corresponding bit in the parent directory’s file protection. Bits in the parent directory’s file protection that indicate delete access do not cause corresponding bits of protection-value to be set, however.

Following is an example of how the protection-value protection mask is defined:

The protection-enable argument is optional. It should be used only when you want to change protection values from the parent directory’s default file protection. The default for protection-enable is a mask of all zero bits, which results in the propagation of the parent directory’s file protection. If the protection-enable mask contains zeros, protection-value is ignored.

protection-value

System/Owner/Group/World protection value of the directory you are creating. The protection-value argument is the address of an unsigned word that contains this protection mask.

The bits of protection-value are set or cleared in the method described in the definition of protection-enable above.

The protection-value argument is optional. The default is a word of all zero bits, which specifies full access for all access categories. Typically, protection-value is not omitted unless protection-enable is also omitted. If protection-enable is omitted, protection-value is ignored.

maximum-versions

Maximum number of versions allowed for files created in the newly created directories. The maximum-versions argument is the address of an unsigned word containing the value of the maximum number of versions.

The maximum-versions argument is optional. The default is the parent directory’s default version limit. If maximum-versions is zero, the maximum number of versions is not limited.

relative-volume-number

Relative volume number within a volume set on which the directory or subdirectory is created. The relative-volume-number argument is the address of an unsigned word containing the relative volume number. The relative-volume-number argument is optional. The default is arbitrary placement within the volume set.

initial-allocation

Initial number of blocks to be allocated to the directory. This argument is useful for creating large directories, for example MAIL.DIR;1. It can improve performance by avoiding the need for later dynamic expansion of the directory.

The initial-allocation argument applies only to Files–11 Level 2 volumes; it is ignored for other volumes.

This argument is the address of an unsigned longword that contains the initial number of blocks to be allocated to the directory.

The initial-allocation argument is optional. The default allocation is 1 block.

Description

LIB$CREATE_DIR creates a directory. You can specify:

Condition Values Returned

Any condition values returned by system services $ASSIGN, $DASSGN, $PARSE, and $QIO, and RTL routines LIB$ANALYZE_SDESC, LIB$ANALYZE_SDESC_ 64, and LIB$GET_EF.

Format

LIB$CREATE_USER_VM_ZONE zone-id [,user-argument] [,user-allocation-procedure] [,user-deallocation-procedure] [,user-reset-procedure] [,user-delete-procedure] [,zone-name]

Returns

Arguments

zone-id

Zone identifier. The zone-id argument is the address of a longword that receives the identifier of the newly created zone.

user-argument

User argument. The user-argument argument is the address of an unsigned longword containing the user argument. LIB$CREATE_USER_VM_ZONE copies the value of user-argument and supplies the value to all user procedures invoked.

user-allocation-procedure

User allocation routine.

user-deallocation-procedure

User deallocation routine.

user-reset-procedure

User routine invoked each time LIB$RESET_VM_ZONE is called for the zone.

user-delete-procedure

User routine invoked when LIB$DELETE_VM_ZONE is called for the zone.

zone-name

Name to be associated with the zone being created. The optional zone-name argument is the address of a descriptor pointing to the zone name. If zone-name is not specified, the zone will not have an associated name.

Description

LIB$CREATE_USER_VM_ZONE creates a user-defined zone in the 32-bit virtual address space. If an error status is returned, the zone is not created.

Each time that one of the heap management routines (LIB$GET_VM, LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE) is called to perform an operation on a user-defined zone, the corresponding user routine that you supplied is used.

You may omit any of the optional user routines. However, if you omit a routine and later call the corresponding heap management routine, the error status LIB$_INVOPEZON will be returned.

Call Format for User Routines

The user routines are called with arguments similar to those passed to LIB$GET_VM, LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE. In each case, the user-argument argument from LIB$CREATE_USER_VM_ZONE is passed to the user routine rather than a zone-id argument.

user-rtn   num-bytes ,base-adr ,user-argument

num-bytes

Number of contiguous bytes to allocate or free. The num-bytes argument is the address of a longword integer containing the number of bytes. The value of num-bytes must be greater than zero.

base-adr

Virtual address of the first contiguous block of bytes allocated or freed. The base-adr argument is the address of an unsigned longword containing this base address. (This argument is write-only for a get routine and read-only for a free routine.)

user-argument

User argument. LIB$CREATE_USER_VM_ZONE copies user-argument as it is supplied to all user routines invoked.

The status value returned by your routine is returned as the status value for the corresponding call to LIB$GET_VM or LIB$FREE_VM.

The zone-id value that is returned can be used in calls to LIB$SHOW_VM_ZONE and LIB$VERIFY_VM_ZONE.

The call format for a user reset or delete routine is as follows:

user-rtn user-argument

user-argument

User argument. LIB$CREATE_USER_VM_ZONE copies user-argument as it is supplied to all user routines invoked.

The status value returned by your routine is returned as the status value for the corresponding call to LIB$RESET_VM_ZONE or LIB$DELETE_VM_ZONE.

Condition Values Returned

Format

LIB$CREATE_USER_VM_ZONE_64 zone-id [,user-argument] [,user-allocation-procedure] [,user-deallocation-procedure] [,user-reset-procedure] [,user-delete-procedure] [,zone-name]

Returns

Arguments

zone-id

Zone identifier. The zone-id argument is the address of a quadword that receives the identifier of the newly created zone.

user-argument

User argument. The user-argument argument is the address of an unsigned quadword containing the user argument. LIB$CREATE_USER_VM_ZONE_64 copies the value of user-argument and supplies the value to all user procedures invoked.

user-allocation-procedure

User allocation routine.

user-deallocation-procedure

User deallocation routine.

user-reset-procedure

User routine invoked each time LIB$RESET_VM_ZONE_64 is called for the zone.

user-delete-procedure

User routine invoked when LIB$DELETE_VM_ZONE_64 is called for the zone.

zone-name

Name to be associated with the zone being created. The optional zone-name argument is the address of a descriptor pointing to the zone name. If zone-name is not specified, the zone will not have an associated name.

Description

LIB$CREATE_USER_VM_ZONE_64 creates a user-defined zone in the 64-bit virtual address space. If an error status is returned, the zone is not created.

Each time that one of the heap management routines (LIB$GET_VM_64, LIB$FREE_VM_64, LIB$RESET_VM_ZONE_64, or LIB$DELETE_VM_ZONE_ 64) is called to perform an operation on a user-defined zone, the corresponding user routine that you supplied is used.

You may omit any of the optional user routines. However, if you omit a routine and later call the corresponding heap management routine, the error status LIB$_INVOPEZON will be returned.

Call Format for User Routines

The user routines are called with arguments similar to those passed to LIB$GET_ VM_64, LIB$FREE_VM_64, LIB$RESET_VM_ZONE_64, or LIB$DELETE_VM_ ZONE_64. In each case, the user-argument argument from LIB$CREATE_ USER_VM_ZONE_64 is passed to the user routine rather than a zone-id argument.

The call format for a user get or free routine is as follows:

user-rtn num-bytes ,base-adr ,user-argument

num-bytes

Number of contiguous bytes to allocate or free. The num-bytes argument is the address of a quadword integer containing the number of bytes. The value of num-bytes must be greater than zero.

base-adr

Virtual address of the first contiguous block of bytes allocated or freed. The base-adr argument is the address of an unsigned quadword containing this base address. (This argument is write-only for a get routine and read-only for a free routine.)

user-argument

User argument. LIB$CREATE_USER_VM_ZONE_64 copies user-argument as it is supplied to all user routines invoked.

The status value returned by your routine is returned as the status value for the corresponding call to LIB$GET_VM_64 or LIB$FREE_VM_64.

The zone-id value that is returned can be used in calls to LIB$SHOW_VM_ZONE_64 and LIB$VERIFY_VM_ZONE_64.

The call format for a user reset or delete routine is as follows:

user-rtn user-argument

user-argument

User argument. LIB$CREATE_USER_VM_ZONE_64 copies user-argument as it is supplied to all user routines invoked.

The status value returned by your routine is returned as the status value for the corresponding call to LIB$RESET_VM_ZONE_64 or LIB$DELETE_VM_ZONE_64.

Condition Values Returned

Format

LIB$CREATE_VM_ZONE zone-id [,algorithm] [,algorithm-argument] [,flags] [,extend-size] [,initial-size] [,block-size] [,alignment] [,page-limit] [,smallest-block-size] [,zone-name] [,get-page] [,free-page]

Returns

Arguments

zone-id

Zone identifier. The zone-id argument is the address of a longword that is set to the zone identifier of the newly created zone.

algorithm

Algorithm. The algorithm argument is the address of a longword integer that contains a value representing one of the LIB$VM algorithms. Use one of the predefined symbols to specify this value.

If algorithm is not specified, a default of 1 (first fit) is used.

algorithm-argument

Algorithm argument. The algorithm-argument argument is the address of a longword integer that contains a value specific to the particular allocation algorithm as shown in the following table.

The algorithm-argument argument must be specified if you are using the quick-fit, frequent-sizes or fixed-size-blocks algorithms. However, this argument is optional, but ignored, if you are using the first-fit algorithm.

flags

Flags. The flags argument is the address of a longword integer that contains flag bits that control various options, as follows:

Bits 8 through 31 are reserved and must be 0.

This is an optional argument. If flags is omitted, the default of 0 (no fill and no boundary tags) is used.

extend-size

Zone extend size. The extend-size argument is the address of a longword integer that contains the number of (512-byte) pages on VAX systems or pagelets on Alpha and I64 systems to be added to the zone each time it is extended.

The value of extend-size must be greater than or equal to 1.

This is an optional argument. If extend-size is not specified, a default of 16 pages on VAX systems or pagelets on Alpha and I64 systems is used.

initial-size

Initial size for the zone. The initial-size argument is the address of a longword integer that contains the number of (512-byte) pages on VAX systems or pagelets on Alpha and I64 systems to be allocated for the zone as the zone is created.

This is an optional argument. If you specify a value for initial-size, the value must be greater than or equal to 0; otherwise, LIB$_INVARG is returned. If initial-size is not specified or is specified as 0, no pages on VAX systems or pagelets on Alpha and I64 systems are allocated when the zone is created. The first call to LIB$GET_VM for the zone allocates extend-size pages on VAX systems or pagelets on Alpha and I64 systems.

block-size

Block size of the zone. The block-size argument is the address of a longword integer specifying the allocation quantum (in bytes) for the zone. All blocks allocated are rounded up to a multiple of block-size.

The value of block-size must be a power of 2 between 8 and 512. This is an optional argument. If block-size is not specified, a default of 8 is used.

alignment

Block alignment. The alignment argument is the address of a longword integer that specifies the required address alignment (in bytes) for each block allocated.

The value of alignment must be a power of 2 between 4 and 512. This is an optional argument. If alignment is not specified, a default of 8 (quadword alignment) is used.

page-limit

Maximum page limit. The page-limit argument is the address of a longword integer that specifies the maximum number of (512-byte) pages on VAX systems or pagelets on Alpha and I64 systems that can be allocated for the zone. The value of page-limit must be greater than or equal to 0. Note that part of the zone is used for header information.

This is an optional argument. If page-limit is not specified or is specified as 0, the only limit is the total process virtual address space limit imposed by OpenVMS. If page-limit is specified, then initial-size must also be specified.

smallest-block-size

Smallest block size. The smallest-block-size argument is the address of a longword integer that specifies the smallest block size (in bytes) that has a lookaside list for the quick fit algorithm.

If smallest-block-size is not specified, the default of block-size is used. That is, lookaside lists are provided for the first n multiples of block-size.

zone-name

Name to be associated with the zone being created. The optional zone-name argument is the address of a descriptor pointing to the zone name. If zone-name is not specified, the zone will not have an associated name.

get-page

Routine that allocates memory. The number and type of the arguments to this routine must match those of the LIB$GET_VM_PAGE routine. If get-page is not specified or is specified as 0, the LIB$GET_VM_PAGE routine is used to allocate memory.

free-page

Routine that deallocates memory. The number and type of the arguments to this routine must match those of the LIB$FREE_VM_PAGE routine. If free-page is not specified or if free-page is specified as 0, the LIB$FREE_VM_PAGE routine is used to deallocate memory.

Description

LIB$CREATE_VM_ZONE creates a new storage zone. The zone identifier value that is returned can be used in calls to LIB$GET_VM, LIB$FREE_VM, LIB$RESET_VM_ZONE, LIB$DELETE_VM_ZONE, LIB$SHOW_VM_ZONE, LIB$VERIFY_VM_ZONE, and LIB$CREATE_USER_VM_ZONE.

The following restrictions apply when you are creating a zone:

If an error status is returned, the zone is not created.

Condition Values Returned

Format

LIB$CREATE_VM_ZONE_64 zone-id [,algorithm] [,algorithm-argument] [,flags] [,extend-size] [,initial-size] [,block-size] [,alignment] [,page-limit] [,smallest-block-size] [,zone-name] [,get-page] [,free-page]

Returned

Arguments

zone-id

Zone identifier. The zone-id argument is the address of a quadword that is set to the zone identifier of the newly created zone.

algorithm

Algorithm. The algorithm argument is the address of a quadword integer that represents the code for one of the LIB$VM algorithms. Use one of the following predefined symbols to specify this value:

If algorithm is not specified, a default of 1 (first fit) is used.

algorithm-argument

Algorithm argument. The algorithm-argument argument is the address of a quadword integer that contains a value specific to the particular allocation algorithm.

The algorithm-argument argument must be specified if you are using the quick-fit, frequent-sizes or fixed-size-blocks algorithms. However, this argument is optional, but ignored, if you are using the first-fit algorithm.

flags

Flags. The flags argument is the address of a quadword integer that contains flag bits that control various options, as follows:

Bits 8 through 63 are reserved and must be 0.

This is an optional argument. If flags is omitted, the default of 0 (no fill and no boundary tags) is used.

extend-size

Zone extend size. The extend-size argument is the address of a quadword integer that contains the number of Alpha and I64 pagelets to be added to the zone each time it is extended.

The value of extend-size must be greater than or equal to 1.

This is an optional argument. If extend-size is not specified, a default of 16 Alpha or I64 pagelets is used.

initial-size

Initial size for the zone. The initial-size argument is the address of a quadword integer that contains the number of Alpha or I64 pagelets to be allocated for the zone as the zone is created.

This is an optional argument. If you specify a value for initial-size, the value must be greater than or equal to 0; otherwise, LIB$_INVARG is returned. If initial-size is not specified or is specified as 0, no Alpha pagelets or I64 are allocated when the zone is created. The first call to LIB$GET_VM_64 for the zone allocates extend-size pagelets on Alpha or I64 systems.

block-size

Block size of the zone. The block-size argument is the address of a quadword integer specifying the allocation quantum (in bytes) for the zone. All blocks allocated are rounded up to a multiple of block-size.

The value of block-size must be a power of 2 between 16 and 512. This is an optional argument. If block-size is not specified, a default of 16 is used.

alignment

Block alignment. The alignment argument is the address of a quadword integer that specifies the required address alignment (in bytes) for each block allocated.

The value of alignment must be a power of 2 between 8 and 512. This is an optional argument. If alignment is not specified, a default of 16 (octaword alignment) is used.

page-limit

Maximum page limit. The page-limit argument is the address of a quadword integer that specifies the maximum number of Alpha or I64 pagelets that can be allocated for the zone. The value of page-limit must be greater than or equal to 0. Note that part of the zone is used for header information.

This is an optional argument. If page-limit is not specified or is specified as 0, the only limit is the total process virtual address space limit imposed by OpenVMS. If page-limit is specified, then initial-size must also be specified.

smallest-block-size

Smallest block size. The smallest-block-size argument is the address of a quadword integer that specifies the smallest block size (in bytes) that has a lookaside list for the quick fit algorithm.

If smallest-block-size is not specified, the default of block-size is used. That is, lookaside lists are provided for the first n multiples of block-size.

zone-name

Name to be associated with the zone being created. The optional zone-name argument is the address of a descriptor pointing to the zone name. If zone-name is not specified, the zone will not have an associated name.

get-page

Routine that allocates memory. The number and type of the arguments to this routine must match those of the LIB$GET_VM_PAGE_64 routine. If get-page is not specified or is specified as 0, the LIB$GET_VM_PAGE_64 routine is used to allocate memory.

free-page

Routine that deallocates memory. The number and type of the arguments to this routine must match those of the LIB$FREE_VM_PAGE_64 routine. If free-page is not specified or if free-page is specified as 0, the LIB$FREE_VM_PAGE_64 routine is used to deallocate memory.

Description

LIB$CREATE_VM_ZONE_64 creates a new storage zone. The zone identifier value that is returned can be used in calls to LIB$GET_VM_64, LIB$FREE_VM_ 64, LIB$RESET_VM_ZONE_64, LIB$DELETE_VM_ZONE_64, LIB$SHOW_VM_ ZONE_64, LIB$VERIFY_VM_ZONE_64, and LIB$CREATE_USER_VM_ZONE_ 64.

The following restrictions apply when you are creating a zone:

If an error status is returned, the zone is not created.

Condition Values Returned

Format

LIB$CRF_INS_KEY control-table ,key-string ,symbol-value ,flags

Returns

None.

Arguments

control-table

Cross-reference table into which LIB$CRF_INS_KEY inserts information about the key. The control-table argument is the address of a signed longword integer pointing to the cross-reference table. You must name this table each time you call a cross-reference routine because you can accumulate information for more than one cross-reference table at a time.

key-string

A counted ASCII string that contains a symbol name or an unsigned binary longword. The key-string argument is the address of a descriptor pointing to the key.

symbol-value

Symbol value, the address of which LIB$CRF_INS_KEY inserts in the cross-reference table. The symbol-value argument is the address of a signed longword integer containing this value. Both the key and value addresses must be permanent addresses in the user’s symbol table.

flags

Value used in selecting the contents of the KEY2 and VAL2 fields; flags is stored with the entry. The flags argument is the address of an unsigned longword containing the flags. When preparing the output line, LIB$CRF_OUTPUT uses flags and the 16-bit mask in the field descriptor table to extract the data. The high-order bit of the word is reserved for LIB$CRF_INS_KEY.

Description

LIB$CRF_INS_KEY stores information to be printed in the KEY1, KEY2, VAL1, and VAL2 fields. When you call this routine, an entry for the key is made in the cross-reference table if the key is not present in the table. If the key is present, only the value address and value flag fields are updated.

Condition Values Returned

None.

Format

LIB$CRF_INS_REF control-table ,longword-integer-key ,reference-string ,longword-integer-reference ,ref-definition-indicator

Returns

None.

Arguments

control-table

Control table associated with this cross-reference. The control-table argument is the address of an array containing the control table.

longword-integer-key

Key referred to by LIB$CRF_INS_REF. The longword-integer-key argument is the address of a signed longword integer containing the key. The key is a counted ASCII string that contains a symbol name or an unsigned binary longword. It must be a permanent address in the user’s symbol table.

reference-string

Counted ASCII string with a maximum of 31 characters, not including the byte count. The reference-string argument is the address of a descriptor pointing to the counted ASCII string.

longword-integer-reference

The 16-bit value used in selecting the contents of the REF1 field. The longword-integer-reference argument is the address of a signed longword integer containing this value. When preparing the output line, LIB$CRF_OUTPUT uses longword-integer-reference and the bit mask in the field descriptor table to extract the data. The high-order bit of the word is reserved for LIB$CRF_INS_ REF.

ref-definition-indicator

Reference/definition indicator that LIB$CRF_INS_REF uses to distinguish between a reference to a symbol and the definition of the symbol. The ref-definition-indicator argument is the address of a signed longword integer containing this indicator. The only difference between processing a symbol reference and a symbol definition is where LIB$CRF_INS_REF stores the information.

Description

LIB$CRF_INS_REF inserts a reference to a key in the cross-reference symbol table. If you attempt to insert reference information for a key that was not specified in a call to LIB$CRF_INS_KEY, LIB$CRF_INS_REF uses the address of the key to locate the symbol name and set the KEY1 field. Once set, either as a result of LIB$CRF_INS_KEY or LIB$CRF_INS_REF, the KEY1 field is never changed. A KEY1 field set by LIB$CRF_INS_REF has a space-filled VAL1 field associated with it unless it is overridden by a subsequent call to LIB$CRF_INS_KEY.

Condition Values Returned

None.

Format

LIB$CRF_OUTPUT control-table ,output-line-width ,page1 ,page2 ,mode-indicator ,delete-save-indicator

Returns

None.

Arguments

control-table

Control table associated with the cross-reference. The control-table argument is the address of an array containing the control table. The table contains the address of the user-supplied routine that prints the lines formatted by LIB$CRF_ OUTPUT.

output-line-width

Width of the output line. The output-line-width argument is the address of a signed longword integer containing the width.

page1

Number of lines on the first page of the output. The page1 argument is the address of a signed longword integer containing this number. This allows the user to reserve space to print header information on the first page of the cross-reference.

page2

Number of lines per page for the other pages. The page2 argument is the address of a signed longword integer containing this number.

mode-indicator

Output mode indicator. The mode-indicator argument is the address of a signed longword integer containing the mode indicator.

delete-save-indicator

Delete/save indicator, which LIB$CRF_OUTPUT uses to determine whether the table's built-in accumulating symbol information is to be saved or deleted once the cross-reference is produced. The delete-save-indicator argument is the address of a signed longword integer containing the delete/save indicator.

The indicator can be either of the following:

Description

Any of these fields can be omitted from the output.

Symbol        Value           Symbol          Value
------        -----           ------          -----
BAS$INSTR     000020B0-RU     BAS$SCRATCH     00002308-RU

KEY1          VAL1    VAL2     KEY1           VAL1    VAL2

Symbol          Value          Defined By     Referenced By ...
------          -----          ----------     -----------------
LIB$FREE_VM     0001E185-R     LIB$VM         ALLGBL

KEY1            VAL1   VAL2     REF2           REF2
                                (CRF$K_DEF)    (CRF$K_REF)

Condition Values Returned

None.

Format

LIB$CURRENCY currency-string [,resultant-length]

Returns

Arguments

currency-string

Currency symbol. The currency-string argument is the address of a descriptor pointing to the currency symbol.

resultant-length

Number of characters that LIB$CURRENCY has written into the currency-string argument, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word containing the length of the currency symbol. If the input string is truncated to the size specified in the currency-string argument, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of currency-string.