1 RTL_Routines The OpenVMS Run-Time Library is a collection of procedures available to native mode images at run time. These library procedures are common to all native mode images, regardless of the language processor used to compile or assemble the program. 2 CVT$ 3 CVT$CONVERT_FLOAT The Convert Floating-Point Data Type routine provides a simplified options-interface for converting a floating-point data type to another supported floating-point data type. Format CVT$CONVERT_FLOAT input_value, input_type_code, output_value, output_type_code, options 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments input_value OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by reference The address of a data area containing a floating-point number that is to be converted. The input_value argument may contain floating-point data in F_Floating, D_Floating, G_Floating, H_ Floating, IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_ Long_Floating, IBM_Short_Floating, or CRAY_Floating format. The value of the input_type_code argument determines the format and size of the input_value argument. input_type_code OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value The value of a longword bit mask specifying the type of floating- point data being passed in the input_value argument. Valid type codes are: Size in input_type_code Format Bytes CVT$K_VAX_F F_Floating 4 CVT$K_VAX_D D_Floating 8 CVT$K_VAX_G G_Floating 8 CVT$K_VAX_H H_Floating 16 CVT$K_IEEE_S IEEE_S_Floating 4 CVT$K_IEEE_T IEEE_T_Floating 8 CVT$K_IEEE_X IEEE_X_Floating 16 CVT$K_IBM_LONG IBM_Long_Floating 8 CVT$K_IBM_SHORT IBM_Short_Floating 4 CVT$K_CRAY CRAY_Floating 8 Declarations for the input_type_code argument are in the $CVTDEF module found in the system symbol libraries. output_value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference The address of a data area that receives the converted floating- point number. The output_value argument can contain floating- point data in F_Floating, D_Floating, G_Floating, H_Floating, IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, IBM_Long_ Floating, IBM_Short_Floating, or CRAY_Floating format. The value of the output_type_code argument determines the size and format of the data placed into the output_value argument. output_type_code OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value The value of a longword bit mask specifying the type of floating- point data that the input_value argument will be converted into and returned in the output_value argument. Valid type codes are: Size in output_type_code Format Bytes CVT$K_VAX_F F_Floating 4 CVT$K_VAX_D D_Floating 8 CVT$K_VAX_G G_Floating 8 CVT$K_VAX_H H_Floating 16 CVT$K_IEEE_S IEEE_S_Floating 4 CVT$K_IEEE_T IEEE_T_Floating 8 CVT$K_IEEE_X IEEE_X_Floating 16 CVT$K_IBM_LONG IBM_Long_Floating 8 CVT$K_IBM_SHORT IBM_Short_Floating 4 CVT$K_CRAY CRAY_Floating 8 Declarations for the output_type_code argument are in the $CVTDEF module found in the system symbol libraries. options OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value Conversion option specifier. The options argument is the address of a longword bit mask in which each option bit set causes the corresponding option to be used during the conversion. The following options can be specified using the options argument: Option Description CVT$M_ROUND_TO_ The default rounding option for NEAREST conversions to IEEE data types. This IEEE Std. 754 rounding mode results in the representable output value nearest to the infinitely precise result. If the two nearest representable values are equally near, the one whose least significant bit is 0 is the result. CVT$M_VAX_ROUNDING The default rounding option for conversions to non-IEEE data types. Performs "traditional" style rounding. This mode results in the representable output value nearest to the infinitely precise result. If the two nearest representable values are equally near, the output value is the closest to either positive infinity or negative infinity, depending on the sign of the input value. CVT$M_TRUNCATE Round the output value toward zero (truncate). CVT$M_ROUND_TO_POS Round the output value toward positive infinity. CVT$M_ROUND_TO_NEG Round the output value toward negative infinity. CVT$M_BIG_ENDIAN Interprets IEEE data types as Big Endian. CVT$M_ERR_UNDERFLOW Report underflow conditions as errors. Declarations for the options argument are in the $CVTDEF module found in the system symbol libraries. 3 CVT$FTOF The Convert Floating-Point Data Type routine converts floating- point data types to other supported floating-point data types and allows additional control over the converted results. CVT$FTOF functionality is also available on other platforms supported by HP. Format status = CVT$FTOF input_value, input_type_code, output_value, output_type_code, options 4 Returns OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by value The status return value is an unsigned longword bit mask containing the condition codes raised by the function. CVT$FTOF returns CVT$K_NORMAL; otherwise, it sets one or more recoverable and unrecoverable conditions. Return status values are in the $CVTDEF module in the system symbol libraries. 4 Arguments input_value OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by reference The address of a data area containing a floating-point number to be converted. The number can be floating-point data in one of the following formats: F_Floating Big_Endian_IEEE_S_Floating D_Floating Big_Endian_IEEE_T_Floating G_Floating Big_Endian_IEEE_X_Floating H_Floating IBM_Long_Floating IEEE_S_Floating IBM_Short_Floating IEEE_T_Floating CRAY_Floating_Single IEEE_X_Floating The value of the input_type_code argument determines the format and size of the input_value argument. input_type_code OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value The value of a longword bit mask specifying the type of floating- point data being passed in the input_value argument. Valid type codes are: Size in Input_type_code Format Bytes CVT$K_VAX_F F_Floating 4 CVT$K_VAX_D D_Floating 8 CVT$K_VAX_G G_Floating 8 CVT$K_VAX_H H_Floating 16 CVT$K_IEEE_S IEEE_S_Floating 4 CVT$K_IEEE_T IEEE_T_Floating 8 CVT$K_IEEE_X IEEE_X_Floating 16 CVT$K_BIG_ENDIAN_IEEE_S Big_Endian_IEEE_S_Floating 4 CVT$K_BIG_ENDIAN_IEEE_T Big_Endian_IEEE_T_Floating 8 CVT$K_BIG_ENDIAN_IEEE_X Big_Endian_IEEE_X_Floating 16 CVT$K_IBM_LONG IBM_Long_Floating 8 CVT$K_IBM_SHORT IBM_Short_Floating 4 CVT$K_CRAY_SINGLE CRAY_Floating 8 Declarations for the input_type_code argument are in the $CVTDEF module found in the system symbol libraries. output_value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference The address of a data area that receives the converted floating- point number. The number can be floating-point data in F_ Floating, D_Floating, G_Floating, H_Floating, IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, Big_Endian_IEEE_S_Floating, Big_Endian_IEEE_T_Floating, Big_Endian_IEEE_X_Floating, IBM_Long_ Floating, IBM_Short_Floating, or CRAY_Floating_Single format. The value of the output_type_code argument determines the size and format of the converted floating-point number. output_type_code OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value The value of a longword bit mask specifying the type of floating- point data that the input_value argument will be converted into and returned in the output_value argument. Valid type codes are: Size in Output_type_code Format Bytes CVT$K_VAX_F F_Floating 4 CVT$K_VAX_D D_Floating 8 CVT$K_VAX_G G_Floating 8 CVT$K_VAX_H H_Floating 16 CVT$K_IEEE_S IEEE_S_Floating 4 CVT$K_IEEE_T IEEE_T_Floating 8 CVT$K_IEEE_X IEEE_X_Floating 16 CVT$K_BIG_ENDIAN_IEEE_S Big_Endian_IEEE_S_Floating 4 CVT$K_BIG_ENDIAN_IEEE_T Big_Endian_IEEE_T_Floating 8 CVT$K_BIG_ENDIAN_IEEE_X Big_Endian_IEEE_X_Floating 16 CVT$K_IBM_LONG IBM_Long_Floating 8 CVT$K_IBM_SHORT IBM_Short_Floating 4 CVT$K_CRAY_SINGLE CRAY_Floating 8 Declarations for the output_type_code argument are in the $CVTDEF module found in the system symbol libraries. options OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value Conversion option specifier. The options argument is the address of a longword bit mask in which each option bit set causes the corresponding option to be used during the conversion. Provide a zero (0) value to the options argument to select default behavior or choose one or more options (status condition option, rounding options, "FORCE" options, CRAY and IBM options) from the following tables. Specify only the options that apply to your conversion. A conflicting or incompatible options argument is reported as an error (CVT$M_INVALID_OPTION). Applicable ConversioOption Description Status Condition Option All CVT$M_REPORT_ALL Report all applicable status conditions as the default. The reporting of recoverable status conditions is disabled by default when this option is not used. Rounding Options All CVT$M_ROUND_TO_ The default rounding option for NEAREST conversions to IEEE data types. This IEEE Std. 754 rounding mode results in the representable output value nearest to the infinitely precise result. If the two nearest representable values are equally near, the one whose least significant bit is 0 is the result. All CVT$M_BIASED_ The default rounding option for ROUNDING conversions to non-IEEE data types. Performs "traditional" style rounding. This mode results in the representable output value nearest to the infinitely precise result. If the two nearest representable values are equally near, the output value is the closest to either positive infinity or negative infinity depending on the sign of the input value. All CVT$M_ROUND_TO_ZERO Round the output value toward zero (truncate). All CVT$M_ROUND_TO_POS Round the output value toward positive infinity. All CVT$M_ROUND_TO_NEG Round the output value toward negative infinity. "FORCE" Options All CVT$M_FORCE_ALL_ Apply all applicable "FORCE" SPECIAL_VALUES options for the current conversion. IEEE CVT$M_FORCE_DENORM_ Force a denormalized IEEE output TO_ZERO value to zero. IEEE CVT$M_FORCE_INF_TO_ Force a positive IEEE infinite MAX_FLOAT output value to +max_float and force a negative IEEE infinite output value to -max_float. IEEE CVT$M_FORCE_ Force an invalid IEEE NaN (not a or VAX INVALID_TO_ZERO number) output value or a VAX ROP (reserved operand) output value to zero. CRAY Format Conversion Options CRAY CVT$M_ALLOW_OVRFLW_ Allow an input/output exponent RANGE_VALUES value > 60000 (8). CRAY CVT$M_ALLOW_UDRFLW_ Allow an input/output exponent RANGE_VALUES value < 20000 (8). IBM Format Conversion Option IBM CVT$M_ALLOW_ Allow unnormalized input UNNORMALIZED_VALUES arguments. Allow an unnormalized output value for a small value that would normalize to zero. The maximum representable floating-point values (max_float) for the IEEE_S_Floating, IEEE_T_Floating, IEEE_X_Floating, Big_ Endian_IEEE_S_Floating, Big_Endian_IEEE_T_Floating, and Big_ Endian_IEEE_X_Floating formats are: Data Type Value for: max_float S Decimal: 3.402823e38 T Decimal: 1.797693134862316e308 X Decimal: 1.189731495357231765085759326628007016196477e4932 Declarations for the options argument are in the $CVTDEF module found in the system symbol libraries. 2 LIB$ 3 LIB$ADAWI The Add Aligned Word with Interlock routine allows the user to perform an interlocked add operation using an aligned word. Format LIB$ADAWI add ,sum ,sign 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments add OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by reference 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 OpenVMS usage:word_signed type: word integer (signed) access: modify mechanism: by reference 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 OpenVMS usage:word_signed type: word integer (signed) access: write only mechanism: by reference 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. 3 LIB$ADDX The Add Two Multiple-Precision Binary Numbers routine adds two signed two's complement integers of arbitrary length. Format LIB$ADDX addend-array ,augend-array ,resultant-array [,array-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments addend-array OpenVMS usage:vector_longword_signed type: unspecified access: read only mechanism: by reference, array reference 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 OpenVMS usage:vector_longword_signed type: unspecified access: read only mechanism: by reference, array reference 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 OpenVMS usage:vector_longword_signed type: unspecified access: write only mechanism: by reference, array reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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. 3 LIB$ADD_TIMES The Add Two Quadword Times routine adds two internal format times. Format LIB$ADD_TIMES time1 ,time2 ,resultant-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments time1 OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:date_time type: quadword (unsigned) access: write only mechanism: by reference 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. 3 LIB$ANALYZE_SDESC The Analyze String Descriptors routine extracts the length and the address at which the data starts for a variety of 32-bit string descriptor classes. Format LIB$ANALYZE_SDESC input-descriptor ,data-length ,data-address 4 Corresponding_JSB_Entry_Point LIB$ANALYZE_SDESC_R2 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments input-descriptor OpenVMS usage:descriptor type: quadword (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference 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 OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference 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. 3 LIB$ANALYZE_SDESC_64 (Alpha and I64 only.) The Analyze String Descriptor routine extracts the length and the address at which the data starts for a variety of 32-bit and 64-bit string descriptor classes. Format LIB$ANALYZE_SDESC_64 input-descriptor ,data-length ,data-address [,descriptor-type] 4 Corresponding_JSB_Entry_Point LIB$ANALYZE_SDESC_R2 Refer to the LIB$ANALYZE_SDESC routine for information about the JSB entry point, LIB$ANALYZE_SDESC_R2. This JSB entry point returns 64-bit results on Alpha and I64 systems. 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments input-descriptor OpenVMS usage:descriptor type: longword (unsigned) or quadword (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: write only mechanism: by reference 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 OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference 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 OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference 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. 3 LIB$ASN_WTH_MBX The Assign Channel with Mailbox routine assigns a channel to a specified device and associates a mailbox with the device. It returns both the device channel and the mailbox channel. Format LIB$ASN_WTH_MBX device-name [,maximum-message-size] [,buffer-quota] ,device-channel ,mailbox-channel 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments device-name OpenVMS usage:device_name type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:word_unsigned type: word integer (unsigned) access: write only mechanism: by reference 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 OpenVMS usage:channel type: word integer (unsigned) access: write only mechanism: by reference 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. 3 LIB$AST_IN_PROG The AST in Progress routine indicates whether an AST is currently in progress. Format LIB$AST_IN_PROG 4 Returns OpenVMS usage:boolean type: boolean access: write only mechanism: by value Truth value that indicates whether an AST is currently in progress (value = 1) or not (value = 0). 4 Arguments None. 3 LIB$ATTACH The Attach Terminal to Process routine requests the calling process's command language interpreter (CLI) to detach the terminal of the calling process and to reattach it to a different process. Format LIB$ATTACH process-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument process-id OpenVMS usage:process_id type: longword integer (unsigned) access: read only mechanism: by reference 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. 3 LIB$BBCCI The Test and Clear Bit with Interlock routine tests and clears a selected bit under memory interlock. LIB$BBCCI makes the VAX BBCCI instruction available as a callable routine. Format LIB$BBCCI position ,bit-zero-address 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value 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. 4 Arguments position OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:unspecified type: address access: read only mechanism: by value 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. 3 LIB$BBSSI The Test and Set Bit with Interlock routine tests and sets a selected bit under memory interlock. LIB$BBSSI makes the VAX BBSSI instruction available as a callable routine. Format LIB$BBSSI position ,bit-zero-address 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value 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. 4 Arguments position OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:unspecified type: address access: read only mechanism: by value 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. 3 LIB$BUILD_NODESPEC The Build a Node-Name Specification routine builds a node-name specification from the primary node name. The output node-name specification can be used for other node-name parsing operations. Format LIB$BUILD_NODESPEC primary-nodename, nodespec [,acs] [,secondary-nodename] [,nodespec-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments primary-nodename OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor 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 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:unsigned_word type: word (unsigned) access: write only mechanism: by reference 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. 3 LIB$CALLG The Call Routine with General Argument List routine calls a routine with an argument list specified as an array of longwords, the first of which is a count of the remaining longwords. LIB$CALLG is a callable version of the VAX CALLG instruction. Format LIB$CALLG argument-list ,user-procedure 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value Return value, if any, of the called routine, unchanged by LIB$CALLG. 4 Arguments argument-list OpenVMS usage:arg_list type: unspecified access: read only mechanism: by reference, array reference 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 OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value Routine that LIB$CALLG calls with the specified argument list. 3 LIB$CALLG_64 (Alpha and I64 only.) The Call Routine with General Argument List routine calls a routine with an argument list specified as an array of quadwords, the first of which is a count of the remaining quadwords. Format LIB$CALLG_64 argument-list ,user-procedure 4 Returns OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: write only mechanism: by value Return value, if any, of the called routine, unchanged by LIB$CALLG_64. 4 Arguments argument-list OpenVMS usage:arg_list type: unspecified access: read only mechanism: by reference, array reference 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 OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value Routine that LIB$CALLG_64 calls with the specified argument list. 3 LIB$CHAR The Transform Byte to First Character of String routine transforms a single 8-bit ASCII character to an ASCII string consisting of a single character followed by trailing spaces, if needed, to fill out the string. The range of the input byte is 0 through 255. Format LIB$CHAR one-character-string ,ascii-code 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments one-character-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor 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 OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference 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. 3 LIB$COMPARE_NODENAME The Compare Two Node Names routine compares two node names to see if they resolve to the same full name. Format LIB$COMPARE_NODENAME nodename1 ,nodename2 ,comparison-result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments nodename1 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference 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. 3 LIB$COMPRESS_NODENAME The Compress a Node Name to Its Short Form Equivalence routine compresses a node name to an unambiguous short form usable within the naming environment where the compression is performed. Format LIB$COMPRESS_NODENAME nodename ,compressed-nodename [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments nodename OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor 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 OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference 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. 3 LIB$CONVERT_DATE_STRING The Convert Date String to Quadword routine converts an absolute date string into an OpenVMS internal format date-time quadword. That is, given an input date/time string of a specified format, LIB$CONVERT_DATE_STRING converts this string to an OpenVMS internal format time. Format LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context] [,flags] [,defaults] [,defaulted-fields] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments date-string OpenVMS usage:time_name type: character-coded text string access: read only mechanism: by descriptor 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 OpenVMS usage:date_time type: quadword (unsigned) access: write only mechanism: by reference 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 OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference 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, HP recommends that users specify a different context cell for each calling thread. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference 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: Field Bit Number Mask Year 0 1 Month 1 2 Day of month 2 4 Hours 3 8 Minutes 4 16 Seconds 5 32 Fractional 6 64 seconds Bits 7 through 31 must be zero and are reserved for use by HP. 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 OpenVMS usage:vector_word_unsigned type: word (unsigned) access: read only mechanism: by reference, array reference 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: o For the date group, the default is the current date. o For the time group, the default is 00:00:00.00. defaulted-fields OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference 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 HP, are zeroed. 3 LIB$CRC The Calculate a Cyclic Redundancy Check routine calculates the cyclic redundancy check (CRC) for a data stream. Format LIB$CRC crc-table ,initial-crc ,stream 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The computed cyclic redundancy check. 4 Arguments crc-table OpenVMS usage:vector_longword_signed type: longword integer (signed) access: read only mechanism: by reference, array reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Initial cyclic redundancy check. The initial-crc argument is the address of a signed longword integer containing the initial cyclic redundancy check. stream OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Data stream for which LIB$CRC is calculating the CRC. The stream argument is the address of a descriptor pointing to the data stream. 3 LIB$CRC_TABLE The Construct a Cyclic Redundancy Check Table routine constructs a 16-longword table that uses a cyclic redundancy check polynomial specification as a bit mask. Format LIB$CRC_TABLE polynomial-coefficient ,crc-table 4 Returns None. 4 Arguments polynomial-coefficient OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:vector_longword_signed type: longword integer (signed) access: write only mechanism: by reference, array reference The 16-longword table that LIB$CRC_TABLE produces. The crc-table argument is the address of a signed longword integer containing the table. 3 LIB$CREATE_DIR The Create a Directory routine creates a directory or subdirectory. Format LIB$CREATE_DIR device-directory-spec [,owner-UIC] [,protection-enable] [,protection-value] [,maximum-versions] [,relative-volume-number] [,initial-allocation] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments device-directory-spec OpenVMS usage:device_name type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:uic type: longword (unsigned) access: read only mechanism: by reference 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: bits 00-15 - Member number bits 16-31 - Group number 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 OpenVMS usage:mask_word type: word (unsigned) access: read only mechanism: by reference 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 following diagram shows the structure of a protection mask. Access is allowed for bits set to 0. World Group Owner System +_______________+_______________+_______________+_______________+ | D | W | E | R | D | W | E | R | D | W | E | R | D | W | E | R | _________________________________________________________________ 15 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: Hexadecimal Mask Name Number Value Protection %XDBFF S:None, O:None, G:E, W:W enable Parent %X13FF S:RWED, O:RWED, G:RW, W:R directory Protection %X37FF S:RWE, O:RWE, G:RWE, W:RW value 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 OpenVMS usage:file_protection type: word (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference 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. 3 LIB$CREATE_USER_VM_ZONE The Create User-Defined Storage Zone routine creates a new user- defined storage zone in the 32-bit virtual address space. Format LIB$CREATE_USER_VM_ZONE zone-id [,user-argument] [,user-allocation-procedure] [,user-deallocation-procedure] [,user-reset-procedure] [,user-delete-procedure] [,zone-name] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments zone-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Zone identifier. The zone-id argument is the address of a longword that receives the identifier of the newly created zone. user-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User allocation routine. user-deallocation-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User deallocation routine. user-reset-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User routine invoked each time LIB$RESET_VM_ZONE is called for the zone. user-delete-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User routine invoked when LIB$DELETE_VM_ZONE is called for the zone. zone-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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. 3 LIB$CREATE_USER_VM_ZONE_64 (Alpha and only.) The Create User-Defined Storage Zone routine creates a new user-defined storage zone in the 64-bit virtual address space. 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] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments zone-id OpenVMS usage:identifier type: quadword (unsigned) access: write only mechanism: by reference Zone identifier. The zone-id argument is the address of a quadword that receives the identifier of the newly created zone. user-argument OpenVMS usage:user_arg type: quadword (unsigned) access: read only mechanism: by reference 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 OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User allocation routine. user-deallocation-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User deallocation routine. user-reset-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User routine invoked each time LIB$RESET_VM_ZONE_64 is called for the zone. user-delete-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User routine invoked when LIB$DELETE_VM_ZONE_64 is called for the zone. zone-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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. 3 LIB$CREATE_VM_ZONE The Create a New Zone routine creates a new storage zone in the 32-bit virtual address space, according to specified arguments. 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] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments zone-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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. Symbol Value Algorithm LIB$K_VM_FIRST_FIT 1 First fit LIB$K_VM_QUICK_FIT 2 Quick fit, lookaside list LIB$K_VM_FREQ_SIZES 3 Frequent sizes, lookaside list LIB$K_VM_FIXED 4 Fixed-size blocks If algorithm is not specified, a default of 1 (first fit) is used. algorithm-argument OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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. Algorithm Value First fit Not used, may be omitted. Quick fit The number of lookaside lists used. The number of lists must be between 1 and 128. Frequent The number of lookaside lists used. The number of sizes lists must be between 1 and 16. Fixed size The fixed request size (in bytes) for each get blocks or free request. The request size must be greater than 0. 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 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Flags. The flags argument is the address of a longword integer that contains flag bits that control various options, as follows: Bit Value Description 0 LIB$M_VM_BOUNDARY_ Boundary tags for faster freeing. TAGS Adds a minimum of 8 bytes to each block. 1 LIB$M_VM_GET_FILL0 LIB$GET_VM; fill with bytes of 0. 2 LIB$M_VM_GET_FILL1 LIB$GET_VM; fill with bytes of FF (hexadecimal). 3 LIB$M_VM_FREE_FILL0 LIB$FREE_VM; fill with bytes of 0. 4 LIB$M_VM_FREE_FILL1 LIB$FREE_VM; fill with bytes of FF (hexadecimal). 5 LIB$M_VM_EXTEND_ Adds extents to existing areas if AREA possible. 6 LIB$M_VM_NO_EXTEND Prevents zone from being extended beyond its initial size. If you specify this flag, you must also specify an initial-size. The extend- size argument is not used. 7 LIB$M_VM_TAIL_LARGE Adds areas larger than extend-size areas to the end of the area list. Allocations that are larger than extend-size can result in new areas. These areas are added to the end of the area list. (This provides better memory reuse when allocating small and very large blocks from the same zone.) 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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. NOTE The extend-size argument does not limit the number of blocks that can be allocated from the zone. The actual extension size is the greater of extend-size and the number of pages on VAX systems or pagelets on Alpha and I64 systems needed to satisfy the LIB$GET_VM call that caused the extension. initial-size OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:procedure type: procedure value access: read only mechanism: by value 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 OpenVMS usage:procedure type: procedure value access: read only mechanism: by value 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. 3 LIB$CREATE_VM_ZONE_64 (Alpha and I64 only.) The Create a New Zone routine creates a new storage zone in the 64-bit virtual address space, according to specified arguments. 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] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments zone-id OpenVMS usage:identifier type: quadword (unsigned) access: write only mechanism: by reference 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 OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference 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: Symbol Value Algorithm LIB$K_VM_FIRST_FIT 1 First fit LIB$K_VM_QUICK_FIT 2 Quick fit, lookaside list LIB$K_VM_FREQ_SIZES 3 Frequent sizes, lookaside list LIB$K_VM_FIXED 4 Fixed-size blocks If algorithm is not specified, a default of 1 (first fit) is used. algorithm-argument OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Algorithm argument. The algorithm-argument argument is the address of a quadword integer that contains a value specific to the particular allocation algorithm. Algorithm Value First fit Not used, may be omitted. Quick fit The number of lookaside lists used. The number of lists must be between 1 and 128. Frequent The number of lookaside lists used. The number of sizes lists must be between 1 and 16. Fixed size The fixed request size (in bytes) for each get blocks or free request. The request size must be greater than 0. 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 OpenVMS usage:mask_quadword type: quadword (unsigned) access: read only mechanism: by reference Flags. The flags argument is the address of a quadword integer that contains flag bits that control various options, as follows: Bit Value Description 0 LIB$M_VM_BOUNDARY_ Boundary tags for faster freeing. TAGS Adds a minimum of 16 bytes to each block. 1 LIB$M_VM_GET_FILL0 LIB$GET_VM_64; fill with bytes of 0. 2 LIB$M_VM_GET_FILL1 LIB$GET_VM_64; fill with bytes of FF (hexadecimal). 3 LIB$M_VM_FREE_FILL0 LIB$FREE_VM_64; fill with bytes of 0. 4 LIB$M_VM_FREE_FILL1 LIB$FREE_VM_64; fill with bytes of FF (hexadecimal). 5 LIB$M_VM_EXTEND_ Adds extents to existing areas if AREA possible. 6 LIB$M_VM_NO_EXTEND Prevents zone from being extended beyond its initial size. If you specify this flag, you must also specify an initial-size. Extend-size is not used. 7 LIB$M_VM_TAIL_LARGE Adds areas larger than extend-size areas to the end of the area list. Allocations that are larger than extend-size can result in new areas. These areas are added to the end of the area list. (This provides better memory re-use when allocating small and very large blocks from the same zone.) 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 OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference 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. NOTE The extend-size argument does not limit the number of blocks that can be allocated from the zone. The actual extension size is the greater of extend-size and the number of Alpha or I64 pagelets needed to satisfy the LIB$GET_VM_64 call that caused the extension. initial-size OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:procedure type: procedure value access: read only mechanism: by value 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 OpenVMS usage:procedure type: procedure value access: read only mechanism: by value 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. 3 LIB$CRF_INS_KEY The Insert Key in Cross-Reference Table routine inserts information about a key into a cross-reference table. Format LIB$CRF_INS_KEY control-table ,key-string ,symbol-value ,flags 4 Returns None. 4 Arguments control-table OpenVMS usage:vector_longword_signed type: longword integer (signed) access: read only mechanism: by reference, array reference 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 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference 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. 3 LIB$CRF_INS_REF The Insert Reference to a Key in the Cross-Reference Table routine inserts a reference to a key in a cross-reference symbol table. Format LIB$CRF_INS_REF control-table ,longword-integer-key ,reference-string ,longword-integer-reference ,ref-definition-indicator 4 Returns None. 4 Arguments control-table OpenVMS usage:vector_longword_signed type: longword integer (signed) access: read only mechanism: by reference, array reference Control table associated with this cross-reference. The control- table argument is the address of an array containing the control table. longword-integer-key OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor 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 OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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. The reference/definition indicator can have either of the following values: Symbolic Name Description CRF$K_REF Reference to a symbol CRF$K_DEF Definition of a symbol 3 LIB$CRF_OUTPUT The Output Cross-Reference Table Information routine extracts the information from the cross-reference tables and formats the output pages. Format LIB$CRF_OUTPUT control-table ,output-line-width ,page1 ,page2 ,mode-indicator ,delete-save-indicator 4 Returns None. 4 Arguments control-table OpenVMS usage:vector_longword_signed type: longword integer (signed) access: read only mechanism: by reference, array reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Width of the output line. The output-line-width argument is the address of a signed longword integer containing the width. page1 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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 OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Output mode indicator. The mode-indicator argument is the address of a signed longword integer containing the mode indicator. This indicator allows the user to select which of three output modes is desired. Output Mode Description CRF$K_VALUES Only the value and key fields are to be printed. LIB$CRF_OUTPUT creates multiple columns across the page. Each column consists of the KEY1, KEY2, VAL1, and VAL2 fields. A minimum of one space between each column is guaranteed. CRF$K_VALS_ Requests a cross-reference summary that has no REFS column space saved for a defining reference. If the user inserted a reference with the CRF$K_DEF indicator, the entry is ignored. CRF$K_DEFS_ Requests a cross-reference summary with the first REFS REF1 and REF2 fields used only for definition references. If no definition reference is provided, the fields are filled with spaces. delete-save-indicator OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference 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: CRF$K_SAVE To preserve the tables for subsequent processing CRF$K_ To delete the tables DELETE 3 LIB$CURRENCY The Get System Currency Symbol routine returns the system's currency symbol. Format LIB$CURRENCY currency-string [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments currency-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Currency symbol. The currency-string argument is the address of a descriptor pointing to the currency symbol. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference 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. 3 LIB$CVTF_FROM_INTERNAL_TIME The Convert Internal Time to External Time (F-Floating-Point Value) routine converts a delta internal OpenVMS system time into an external F-floating time. Format LIB$CVTF_FROM_INTERNAL_TIME operation ,resultant-time ,input-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments operation OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference The conversion to be performed. The operation argument is the address of an unsigned longword specifying the operation. Valid values for operation are the following: Operation Interpretation LIB$K_DELTA_WEEKS_F Fractional weeks LIB$K_DELTA_DAYS_F Fractional days LIB$K_DELTA_HOURS_F Fractional hours LIB$K_DELTA_MINUTES_F Fractional minutes LIB$K_DELTA_SECONDS_F Fractional seconds resultant-time OpenVMS usage:floating_point type: F_floating access: write only mechanism: by reference The external time that results from the conversion. The resultant-time argument is the address of an F-floating-point value containing the result. input-time OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference Delta time to be converted. The input-time argument is the address of an unsigned quadword containing the time. 3 LIB$CVTS_FROM_INTERNAL_TIME (Alpha and I64 only.) The Convert Internal Time to External Time (IEEE S-Floating-Point Value) routine converts a delta internal OpenVMS system time into an external IEEE S-floating time. Format LIB$CVTS_FROM_INTERNAL_TIME operation ,resultant-time ,input-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments operation OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference The conversion to be performed. The operation argument is the address of an unsigned longword specifying the operation. Valid values for operation are the following: Operation Interpretation LIB$K_DELTA_WEEKS_F Fractional weeks LIB$K_DELTA_DAYS_F Fractional days LIB$K_DELTA_HOURS_F Fractional hours LIB$K_DELTA_MINUTES_F Fractional minutes LIB$K_DELTA_SECONDS_F Fractional seconds resultant-time OpenVMS usage:floating_point type: IEEE S_floating access: write only mechanism: by reference The external time that results from the conversion. The resultant-time argument is the address of an IEEE S-floating- point value containing the result. input-time OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference Delta time to be converted. The input-time argument is the address of an unsigned quadword containing the time. 3 LIB$CVTF_TO_INTERNAL_TIME The Convert External Time to Internal Time (F-Floating-Point Value) routine converts an external time interval into an OpenVMS internal format F-floating delta time. Format LIB$CVTF_TO_INTERNAL_TIME operation ,input-time ,resultant-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments operation OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference The conversion to be performed. The operation argument is the address of an unsigned longword specifying the operation. Valid values for operation are the following: Operation Interpretation LIB$K_DELTA_WEEKS_F Fractional weeks LIB$K_DELTA_DAYS_F Fractional days LIB$K_DELTA_HOURS_F Fractional hours LIB$K_DELTA_MINUTES_F Fractional minutes LIB$K_DELTA_SECONDS_F Fractional seconds input-time OpenVMS usage:varying_arg type: F_floating access: read only mechanism: by reference Delta time to be converted. The input-time argument is the address of this input time. The value you supply for input-time must be greater than 0. resultant-time OpenVMS usage:date_time type: quadword (unsigned) access: write only mechanism: by reference The OpenVMS internal format delta time that results from the conversion. The resultant-time argument is the address of an unsigned quadword containing the result. 3 LIB$CVTS_TO_INTERNAL_TIME (Alpha and I64 only.) The Convert External Time to Internal Time (IEEE S-Floating-Point Value) routine converts an external time interval into an OpenVMS internal format IEEE S-floating delta time. Format LIB$CVTS_TO_INTERNAL_TIME operation ,input-time ,resultant-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments operation OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference The conversion to be performed. The operation argument is the address of an unsigned longword specifying the operation. Valid values for operation are the following: Operation Interpretation LIB$K_DELTA_WEEKS_F Fractional weeks LIB$K_DELTA_DAYS_F Fractional days LIB$K_DELTA_HOURS_F Fractional hours LIB$K_DELTA_MINUTES_F Fractional minutes LIB$K_DELTA_SECONDS_F Fractional seconds input-time OpenVMS usage:varying_arg type: IEEE S_floating access: read only mechanism: by reference Delta time to be converted. The input-time argument is the address of this input time. The value you supply for input-time must be greater than 0. resultant-time OpenVMS usage:date_time type: quadword (unsigned) access: write only mechanism: by reference The OpenVMS internal format delta time that results from the conversion. The resultant-time argument is the address of an unsigned quadword containing the result. 3 LIB$CVT_DX_DX The General Data Type Conversion routine converts OpenVMS standard atomic or string data described by a source descriptor to OpenVMS standard atomic or string data described by a destination descriptor. This conversion is supported over a subset of the OpenVMS standard data types. Format LIB$CVT_DX_DX source-item ,destination-item [,word-integer-dest-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments source-item OpenVMS usage:unspecified type: unspecified access: read only mechanism: by descriptor Source item to be converted by LIB$CVT_DX_DX. The source-item argument is the address of a descriptor pointing to the source item to be converted. The type of the item to be converted is contained in the descriptor. destination-item OpenVMS usage:unspecified type: unspecified access: write only mechanism: by descriptor Destination of the conversion. The destination-item argument is the address of a descriptor pointing to the destination item. The destination descriptor specifies the data type to which the source item is converted. word-integer-dest-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length in bytes of the destination item (when that item is a string) that has been converted by LIB$CVT_DX_DX, not including any space filling. The word-integer-dest-length argument contains the address of an unsigned word containing this length. If the destination string is truncated, the returned length reflects the truncation. This word can be used by the calling program to determine if truncation has occurred or to extract the exact length of the string when the string contains space filling. 3 LIB$CVT_FROM_INTERNAL_TIME The Convert Internal Time to External Time routine converts an internal OpenVMS system time (either absolute or delta) into an external time. Format LIB$CVT_FROM_INTERNAL_TIME operation ,resultant-time [,input-time] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments operation OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference The conversion to be performed. The operation argument is the address of an unsigned longword containing the operation. The following table shows valid values for operation: Operation Type Return Range LIB$K_MONTH_OF_YEAR Absolute 1 to 12 LIB$K_DAY_OF_YEAR Absolute 1 to 366 LIB$K_HOUR_OF_YEAR Absolute 1 to 8784 LIB$K_MINUTE_OF_YEAR Absolute 1 to 527,040 LIB$K_SECOND_OF_YEAR Absolute 1 to 31,622,400 LIB$K_DAY_OF_MONTH Absolute 1 to 31 LIB$K_HOUR_OF_MONTH Absolute 1 to 744 LIB$K_MINUTE_OF_MONTH Absolute 1 to 44,640 LIB$K_SECOND_OF_MONTH Absolute 1 to 2,678,400 LIB$K_DAY_OF_WEEK Absolute 1 to 7 LIB$K_HOUR_OF_WEEK Absolute 1 to 168 LIB$K_MINUTE_OF_WEEK Absolute 1 to 10,080 LIB$K_SECOND_OF_WEEK Absolute 1 to 604,800 LIB$K_HOUR_OF_DAY Absolute 0 to 23 LIB$K_MINUTE_OF_DAY Absolute 0 to 1439 LIB$K_SECOND_OF_DAY Absolute 0 to 86,399 LIB$K_MINUTE_OF_HOUR Absolute 0 to 59 LIB$K_SECOND_OF_HOUR Absolute 0 to 3599 LIB$K_SECOND_OF_MINUTE Absolute 0 to 59 LIB$K_JULIAN_DATE Absolute Julian date LIB$K_DELTA_WEEKS Delta LIB$K_DELTA_DAYS Delta LIB$K_DELTA_HOURS Delta LIB$K_DELTA_MINUTES Delta LIB$K_DELTA_SECONDS Delta resultant-time OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference The external time that results from the conversion. The resultant-time argument is the address of an unsigned longword containing the result. input-time OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference Optional absolute or delta time to be converted. The input-time argument is the address of an unsigned quadword containing the time. If you do not supply a value for input-time, the current system time is used. 3 LIB$CVT_TO_INTERNAL_TIME The Convert External Time to Internal Time routine converts an external time interval into an OpenVMS internal format delta time. Format LIB$CVT_TO_INTERNAL_TIME operation ,input-time ,resultant-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments operation OpenVMS usage:function_code type: longword (unsigned) access: read only mechanism: by reference The conversion to be performed. The operation argument is the address of an unsigned longword specifying the operation. Valid values for operation are the following: Operation Interpretation LIB$K_DELTA_WEEKS Whole weeks in delta time LIB$K_DELTA_DAYS Whole days in delta time LIB$K_DELTA_HOURS Whole hours in delta time LIB$K_DELTA_MINUTES Whole minutes in delta time LIB$K_DELTA_SECONDS Whole seconds in delta time input-time OpenVMS usage:varying_arg type: longword (signed) access: read only mechanism: by reference Delta time to be converted. The input-time argument is the address of this input time. The value you supply for input-time must be greater than 0. resultant-time OpenVMS usage:date_time type: quadword (unsigned) access: write only mechanism: by reference The OpenVMS internal format delta time that results from the conversion. The resultant-time argument is the address of an unsigned quadword containing the result. 3 LIB$CVT_VECTIM The Convert 7-Word Vector to Internal Time routine converts a 7-word vector into an OpenVMS internal format delta or absolute time. Format LIB$CVT_VECTIM input-time ,resultant-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments input-time OpenVMS usage:vector_word_unsigned type: word (unsigned) access: read only mechanism: by reference, array reference Time to be converted. The input-time argument is the address of a 7-word structure containing this time. This vector directly corresponds to a $NUMTIM timbuf structure. The input-time argument can represent an absolute or a delta time. In order for input-time to represent a delta time, the year since 0 and month of year fields must equal zero. If those fields do not equal zero, an absolute time is returned. resultant-time OpenVMS usage:date_time type: quadword (unsigned) access: write only mechanism: by reference The OpenVMS internal format delta or absolute time that results from the conversion. The resultant-time argument is the address of an unsigned quadword containing the result. 3 LIB$CVT_xTB The Convert Numeric Text to Binary routines return a binary representation of the ASCII text string representation of a decimal, hexadecimal, or octal number. Format LIB$CVT_DTB byte-count ,numeric-string ,result LIB$CVT_HTB byte-count ,numeric-string ,result LIB$CVT_OTB byte-count ,numeric-string ,result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments byte-count OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by value Byte count of the input ASCII text string. The byte-count argument is a signed longword integer containing the byte count of the input string. numeric-string OpenVMS usage:char_string type: character string access: read only mechanism: by reference ASCII text string representation of a decimal, hexadecimal, or octal number that LIB$CVT_xTB converts to binary representation. The numeric-string argument is the address of a character string containing this input string to be converted. LIB$CVT_xTB allows only an optional plus (+) or minus (-) sign followed by a string of decimal, hexadecimal, or octal characters appropriate to the routine being called. result OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Binary representation of the input string. The result argument is the address of a signed longword integer containing the converted string. 3 LIB$CVT_xTB_64 (Alpha and I64 only.) The Convert Numeric Text to Binary routines return a binary representation of the ASCII text string representation of a decimal, hexadecimal, or octal number. Format LIB$CVT_DTB_64 byte-count ,numeric-string ,result LIB$CVT_HTB_64 byte-count ,numeric-string ,result LIB$CVT_OTB_64 byte-count ,numeric-string ,result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments byte-count OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by value Byte count of the input ASCII text string. The byte-count argument is a signed longword integer containing the byte count of the input string. numeric-string OpenVMS usage:char_string type: character string access: read only mechanism: by reference ASCII text string representation of a decimal, hexadecimal, or octal number that LIB$CVT_xTB_64 converts to binary representation. The numeric-string argument is the address of a character string containing this input string to be converted. LIB$CVT_xTB_64 allows only an optional plus (+) or minus (-) sign followed by a string of decimal, hexadecimal, or octal characters appropriate to the routine being called. result OpenVMS usage:quadword_signed type: quadword integer (signed) access: write only mechanism: by reference Binary representation of the input string. The result argument is the address of a signed quadword integer containing the converted string. 3 LIB$DATE_TIME The Date and Time Returned as a String routine returns the OpenVMS system date and time in the semantics of a user-provided string. Format LIB$DATE_TIME date-time-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument date-time-string OpenVMS usage:time_name type: character string access: write only mechanism: by descriptor Destination string into which LIB$DATE_TIME writes the system date and time. The date-time-string argument is the address of a descriptor pointing to the destination string. This string is 23 characters long; its format is as follows: dd-mmm-yyyy hh:mm:ss.hh See the HP 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. 3 LIB$DAY The Day Number Returned as a Longword Integer routine returns the number of days since the system zero date of November 17, 1858, or the number of days from November 17, 1858, to a user-supplied date. Format LIB$DAY number-of-days [,user-time] [,day-time] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-days OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Number of days since the system zero date. The number-of-days argument is the address of a signed longword integer containing the day number. user-time OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference User-supplied time, in 100-nanosecond units. The user-time argument is the address of a signed quadword integer containing the user time. A positive value indicates an absolute time, while a negative value indicates a delta time. This is an optional argument. If user-time is omitted, the default is the current system time. This quadword time value is obtained by calling the $BINTIM system service. If time is passed as zero by value, the numeric value for the current day is returned. If time is passed as a zero by reference, the number returned represents the day of November 17, 1858, rather than the current day. day-time OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Number of 10-millisecond units since midnight of the user-time argument. The day-time argument is the address of a signed longword integer into which LIB$DAY writes this number of units. 3 LIB$DAY_OF_WEEK The Show Numeric Day of Week routine returns the numeric day of the week for an input time value. If 0 is the input time value, the current day of the week is returned. The days are numbered 1 through 7, with Monday as day 1 and Sunday as day 7. Format LIB$DAY_OF_WEEK [user-time,] day-number 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments user-time OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference Time to be translated to a day of the week, or zero. The optional user-time argument is the address of an unsigned quadword containing the value of time. Time must be supplied as an absolute system time. To obtain this time value in proper quadword format, call the $BINTIM system service. If time is passed as zero by value, the numeric value for the current day is returned. If time is passed as a zero by reference, the number returned represents the day of November 17, 1858. If the user-time argument is omitted, it is equivalent to passing a zero by value. day-number OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Numeric day of week. The day-number argument is the address of a longword into which LIB$DAY_OF_WEEK writes the integer value representing the day of the week. 3 LIB$DECODE_FAULT The Decode Instruction Stream During Fault routine is a tool for building condition handlers that process instruction fault exceptions. It is called from a condition handler. This routine is not available to native OpenVMS Alpha and I64 programs but is available to translated VAX images. Format LIB$DECODE_FAULT signal-arguments ,mechanism-arguments ,user-procedure [,unspecified-user-argument] [,instruction-definitions] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments signal-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference Signal arguments array that was passed from the OpenVMS operating system to your condition handler. The signal-arguments argument is the address of the signal arguments array. mechanism-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference Mechanism arguments array that was passed from OpenVMS to your condition handler. The mechanism-arguments argument is the address of the mechanism arguments array. user-procedure OpenVMS usage:procedure type: procedure value access: call after stack unwind mechanism: by descriptor, procedure descriptor User-supplied action routine that LIB$DECODE_FAULT calls to handle the exception. The user-procedure argument is the address of a descriptor pointing to your user action routine. The user- procedure argument may be of type "procedure value" when called by languages with up-level addressing. If user-procedure is not of type "bound routine value," it is assumed to be the address of an entry mask. unspecified-user-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value Additional information passed from your handler without interpretation to your user action routine. The unspecified- user-argument argument contains the value of this additional information. The unspecified-user-argument argument is optional; if it is omitted, zero is used as the default. instruction-definitions OpenVMS usage:vector_byte_unsigned type: byte (unsigned) access: read only mechanism: by reference, array reference Array of bytes specifying instruction opcodes and operand definitions that are to replace or supplement the standard instruction definitions. The instruction-definitions argument is the address of this array. If instruction-definitions is omitted, only the standard instruction definitions are used. If supplied, instruction- definitions is searched first, followed by the standard definitions. Each instruction definition consists of a series of bytes, the first one or two of which is the instruction opcode. If the instruction is a 2-byte opcode, the escape byte, which must be hex FD, FE, or FF, is placed in the first of the two bytes. Following the opcode may be from 0 to 16 operand definition bytes. These bytes indicate the operand's access type and data type. The end of each instruction definition is denoted by a byte containing the value LIB$K_DCFOPR_END (zero). The list of instruction definitions is terminated by two bytes, each of which contains the value -1 (hexadecimal FF). 3 LIB$DEC_OVER The Enable or Disable Decimal Overflow Detection routine enables or disables decimal overflow detection for the calling routine activation. The previous decimal overflow setting is returned. This routine is available on OpenVMS Alpha and I64 systems in translated form and is applicable to translated VAX images only. Format LIB$DEC_OVER new-setting 4 Returns OpenVMS usage:longword_unsigned type: longword integer (unsigned) access: write only mechanism: by value The old decimal overflow enable setting (the previous contents of SF$W_PSW[PSW$V_DV] in the caller's frame). 4 Argument new-setting OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference New decimal overflow enable setting. The new-setting argument is the address of an unsigned longword that contains the new decimal overflow enable setting. Bit 0 set to 1 means enable; bit 0 set to 0 means disable. 3 LIB$DELETE_FILE The Delete One or More Files routine deletes one or more files. The specification of the files to be deleted may include wildcards. LIB$DELETE_FILE is similar in function to the DCL command DELETE. Format LIB$DELETE_FILE filespec [,default-filespec] [,related-filespec] [,user-success-procedure] [,user-error-procedure] [,user-confirm-procedure] [,user-specified-argument] [,resultant-name] [,file-scan-context] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the OpenVMS Record Management Services (RMS) file specification of the files to be deleted. The filespec argument is the address of a descriptor pointing to the file specification. If the specification includes wildcards, each file that matches the specification is deleted. If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string must not contain more characters than specified by NAML$C_MAXRSS, otherwise the string must not contain more than 255 characters. Any string class is supported. default-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Default file specification of the files to be deleted. The default-filespec argument is the address of a descriptor pointing to the default file specification. This is an optional argument; if the argument is omitted, the default is the null string. Any string class is supported. See the OpenVMS Record Management Services Reference Manual for information about default file specifications. related-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Related file specification of the files to be deleted. The related-filespec argument is the address of a descriptor pointing to the related file specification. Any string class is supported. This is an optional argument; if the argument is omitted, the default is the null string. Input file parsing is used. See the OpenVMS Record Management Services Reference Manual for information on related file specifications and input file parsing. The related file specification is useful when you are processing lists of file specifications. Unspecified portions of the file specification are inherited from the last file processed. user-success-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied success routine that LIB$DELETE_FILE calls after it successfully deletes a file. The success routine can be used to display a log of the files that were deleted. user-error-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied error routine that LIB$DELETE_FILE calls when it detects an error. The error routine returns a success/fail value that LIB$DELETE_ FILE uses to determine if more files should be processed. user-confirm-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied confirm routine that LIB$DELETE_FILE calls before each file is deleted. The value returned by the confirm routine determines whether or not the file will be deleted. The confirm routine can be used to select specific files for deletion based on criteria such as expiration date, size, and so on. user-specified-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value User-supplied argument that LIB$DELETE_FILE passes to the error, success, and confirm routines each time they are called. Whatever mechanism is used to pass user-specified-argument to LIB$DELETE_ FILE is also used to pass it to the routines. This is an optional argument; if the argument is omitted, zero is passed by value. resultant-name OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which LIB$DELETE_FILE writes the RMS resultant file specification of the last file processed. The resultant-name argument is the address of a descriptor pointing to the resultant name. If present, resultant-name is used to store the file specification passed to the user-supplied routines, instead of a default class S, type T string. Therefore, this argument should be specified when the user-supplied routines are used and those routines require a descriptor type other than class S, type T. Any string class is supported. If you specify one or more of the user-supplied action routines, the descriptor used to pass resultant-name must be: o Of the same class as the descriptor required by the filespec argument of any action routines. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use. o (Alpha and I64 only) Of the same form as the descriptor required by the filespec argument of all action routines. For example, if the filespec argument of an action routine uses a 64-bit descriptor, then the resultant-name argument must also use a 64-bit descriptor. file-scan-context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context for deleting a list of file specifications. The file- scan-context argument is the address of a longword containing the context value. You must initialize the file scan context to zero before the first of a series of calls to LIB$DELETE_FILE. LIB$FILE_SCAN uses this context to retain the file context for multiple input files. You must specify this context only when you are dealing with multiple input files, as the DCL command DELETE does. You may deallocate the context allocated by LIB$FILE_SCAN by calling LIB$FILE_SCAN_END after all calls to LIB$DELETE_FILE have been completed. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference User flags. The flags argument is the address of an unsigned longword containing the user flags. The flag bits and their corresponding symbols are described in the following table: Bit Symbol Description 0 Reserved to HP. 1 Reserved to HP. 2 LIB$M_FIL_LONG_ (Alpha or I64 only) If set, LIB$DELETE_ NAMES FILE can process file names with a maximum length of NAML$C_MAXRSS. If clear, LIB$DELETE_FILE can process file specifications with a maximum length of 255 (default). 3 LIB$DELETE_LOGICAL The Delete Logical Name routine requests the calling process' command language interpreter (CLI) to delete a supervisor-mode process logical name. LIB$DELETE_LOGICAL provides the same function as the DCL command DEASSIGN. Format LIB$DELETE_LOGICAL logical-name [,table-name] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments logical-name OpenVMS usage:logical_name type: character string access: read only mechanism: by descriptor Logical name to be deleted. The logical-name argument is the address of a descriptor pointing to this logical name string. The maximum length of a logical name is 255 characters. table-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the table from which the logical name is to be deleted. The table-name argument is the address of a descriptor pointing to this name string. This is an optional argument. If the argument is omitted, the LNM$PROCESS table is used. 3 LIB$DELETE_SYMBOL The Delete CLI Symbol routine requests the calling process's command language interpreter (CLI) to delete an existing CLI symbol. Format LIB$DELETE_SYMBOL symbol [,table-type-indicator] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments symbol OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the symbol to be deleted by LIB$DELETE_SYMBOL. The symbol argument is the address of a descriptor pointing to this symbol string. The symbol name is converted to uppercase, and trailing blanks are removed before use. Symbol must begin with a letter, a digit, a dollar sign ($), a hyphen (-), or an underscore (_). The maximum length of symbol is 255 characters. table-type-indicator OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Indicator of the table that contains the symbol to be deleted. The table-type-indicator argument is the address of a signed longword integer that is this table indicator. If table-type-indicator is omitted, the local symbol table is used. The following are possible values for the table-type- indicator argument: Symbolic Name Value Table Used LIB$K_CLI_LOCAL_ 1 Local symbol table SYM LIB$K_CLI_GLOBAL_ 2 Global symbol table SYM 3 LIB$DELETE_VM_ZONE The Delete Virtual Memory Zone routine deletes a zone from the 32-bit virtual address space and returns all pages on VAX systems or pagelets on Alpha and I64 systems owned by the zone to the processwide 32-bit page pool. Format LIB$DELETE_VM_ZONE zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument zone-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Zone identifier. The zone-id is the address of a longword that contains the identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE. 3 LIB$DELETE_VM_ZONE_64 (Alpha and I64 only.) The Delete Virtual Memory Zone routine deletes a zone from the 64-bit virtual address space and returns all Alpha and I64 system pagelets owned by the zone to the processwide 64-bit page pool. Format LIB$DELETE_VM_ZONE_64 zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument zone-id OpenVMS usage:identifier type: quadword (unsigned) access: read only mechanism: by reference Zone identifier. The zone-id is the address of a quadword that contains the identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64. 3 LIB$DIGIT_SEP The Get Digit Separator Symbol routine returns the system's digit separator symbol. Format LIB$DIGIT_SEP digit-separator-string [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments digit-separator-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Digit separator symbol returned by LIB$DIGIT_SEP. The digit- separator-string argument is the address of a descriptor pointing to the digit separator. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of characters written into digit-separator-string, 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 digit separator symbol. If the input string is truncated to the size specified in the digit- separator-string descriptor, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of digit-separator- string. 3 LIB$DISABLE_CTRL The Disable CLI Interception of Control Characters routine requests the calling process's command language interpreter (CLI) to not intercept the selected control characters when they are entered during an interactive terminal session. LIB$DISABLE_CTRL provides the same function as the DCL command SET NOCONTROL. Format LIB$DISABLE_CTRL disable-mask [,old-mask] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments disable-mask OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask indicating which control characters are not to be intercepted. The disable-mask argument is the address of an unsigned longword containing this bit mask. Each of the 32 bits corresponds to one of the 32 possible control characters. If a bit is set, the corresponding control character is no longer intercepted by the CLI. Currently, only bits 20 and 25, corresponding to Ctrl/T and Ctrl/Y, are recognized. The following mask is defined in symbol libraries supplied by HP to specify the value of disable-mask: Symbol Hex Value Function LIB$M_CLI_ %X'00100000' Disables Ctrl/T CTRLT LIB$M_CLI_ %X'02000000' Disables Ctrl/Y CTRLY If a set bit does not correspond to a character that the CLI can intercept, LIB$DISABLE_CTRL returns an error. old-mask OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Previous bit mask. The old-mask argument is the address of an unsigned longword into which LIB$DISABLE_CTRL writes the old bit mask. The old bit mask is of the same form as disable-mask and indicates those control characters that were previously enabled. It may therefore be given to LIB$ENABLE_CTRL to reinstate the previous condition. 3 LIB$DO_COMMAND The Execute Command routine stops program execution and directs the command language interpreter (CLI) to execute a command that you supply as the argument. If successful, LIB$DO_COMMAND does not return control to the calling program. Instead, LIB$DO_ COMMAND begins execution of the specified command. If you want control to return to the caller, use LIB$SPAWN instead. Format LIB$DO_COMMAND command-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument command-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Text of the command that LIB$DO_COMMAND executes. The command- string argument is the address of a descriptor pointing to the command text. The maximum length of the command is 255 characters. 3 LIB$EDIV The Extended-Precision Divide routine performs extended-precision division. LIB$EDIV makes the VAX EDIV instruction available as a callable routine. Format LIB$EDIV longword-integer-divisor ,quadword-integer-dividend ,longword-integer-quotient ,remainder 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments longword-integer-divisor OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Divisor. The longword-integer-divisor argument is the address of a signed longword integer containing the divisor. quadword-integer-dividend OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Dividend. The quadword-integer-dividend argument is the address of a signed quadword integer containing the dividend. longword-integer-quotient OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Quotient. The longword-integer-quotient argument is the address of a signed longword integer containing the quotient. remainder OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Remainder. The remainder argument is the address of a signed longword integer containing the remainder. 3 LIB$EMODD The Extended Multiply and Integerize routine (D-Floating-Point Values) allows higher-level language users to perform accurate range reduction of D-floating arguments. On Alpha and I64 systems, D-floating-point values are not supported in full precision in native OpenVMS Alpha and I64 programs. They are precise to 56 bits on VAX systems, 53 or 56 bits in translated VAX images, and 53 bits in native OpenVMS Alpha and I64 programs. Format LIB$EMODD floating-point-multiplier ,multiplier-extension ,floating-point-multiplicand ,integer-portion ,fractional-portion 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments floating-point-multiplier OpenVMS usage:floating_point type: D_floating access: read only mechanism: by reference The multiplier. The floating-point-multiplier argument is a D- floating number. multiplier-extension OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference The left-justified multiplier-extension bits. The multiplier- extension argument is an unsigned byte. floating-point-multiplicand OpenVMS usage:floating_point type: D_floating access: read only mechanism: by reference The multiplicand. The floating-point-multiplicand argument is a D-floating number. integer-portion OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference The integer portion of the result. The integer-portion argument is the address of a signed longword integer containing the integer portion of the result. fractional-portion OpenVMS usage:floating_point type: D_floating access: write only mechanism: by reference The fractional portion of the result. The fractional-portion argument is a D-floating number. 3 LIB$EMODF The Extended Multiply and Integerize routine (F-Floating-Point Values) allows higher-level language users to perform accurate range reduction of F-floating arguments. Format LIB$EMODF floating-point-multiplier ,multiplier-extension ,floating-point-multiplicand ,integer-portion ,fractional-portion 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments floating-point-multiplier OpenVMS usage:floating_point type: F_floating access: read only mechanism: by reference The multiplier. The floating-point-multiplier argument is the address of an F-floating number containing the number. multiplier-extension OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference The left-justified multiplier-extension bits. The multiplier- extension argument is the address of an unsigned byte containing these multiplier extension bits. floating-point-multiplicand OpenVMS usage:floating_point type: F_floating access: read only mechanism: by reference The multiplicand. The floating-point-multiplicand argument is an F-floating number. integer-portion OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference The integer portion of the result. The integer-portion argument is the address of a signed longword integer containing the integer portion of the result. fractional-portion OpenVMS usage:floating_point type: F_floating access: write only mechanism: by reference The fractional portion of the result. The fractional-portion argument is the address of an F-floating number containing the fractional portion of the result. 3 LIB$EMODG The Extended Multiply and Integerize routine (G-Floating-Point Values) allows higher-level language users to perform accurate range reduction of G-floating arguments. Format LIB$EMODG floating-point-multiplier ,multiplier-extension ,floating-point-multiplicand ,integer-portion ,fractional-portion 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments floating-point-multiplier OpenVMS usage:floating_point type: G_floating access: read only mechanism: by reference The multiplier. The floating-point-multiplier argument is a G- floating number. multiplier-extension OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference The left-justified multiplier-extension bits. The multiplier- extension argument is an unsigned word. floating-point-multiplicand OpenVMS usage:floating_point type: G_floating access: read only mechanism: by reference The multiplicand. The floating-point-multiplicand argument is a G-floating number. integer-portion OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference The integer portion of the result. The integer-portion argument is the address of a signed longword integer containing the integer portion of the result. fractional-portion OpenVMS usage:floating_point type: G_floating access: write only mechanism: by reference The fractional portion of the result. The fractional-portion argument is a G-floating number. 3 LIB$EMODH On OpenVMS VAX systems, the Extended Multiply and Integerize routine (H-Floating-Point Values) allows higher-level language users to perform accurate range reduction of H-floating arguments. This routine is not available to native OpenVMS Alpha programs but is available to translated VAX images. Format LIB$EMODH floating-point-multiplier ,multiplier-extension ,floating-point-multiplicand ,integer-portion ,fractional-portion 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments floating-point-multiplier OpenVMS usage:floating_point type: H_floating access: read only mechanism: by reference The multiplier. The floating-point-multiplier argument is an H-floating number. multiplier-extension OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference The left-justified multiplier-extension bits. The multiplier- extension argument is an unsigned word. floating-point-multiplicand OpenVMS usage:floating_point type: H_floating access: read only mechanism: by reference The multiplicand. The floating-point-multiplicand argument is an H-floating number. integer-portion OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference The integer portion of the result. The integer-portion argument is the address of a signed longword integer containing the integer portion of the result. fractional-portion OpenVMS usage:floating_point type: H_floating access: write only mechanism: by reference The fractional portion of the result. The fractional-portion argument is an H-floating number. 3 LIB$EMODS_ (Alpha and I64 only.) The Extended Multiply and Integerize routine (IEEE S-Floating-Point Values) allows higher-level language users to perform accurate range reduction of IEEE S- floating arguments. Format LIB$EMODS floating-point-multiplier ,multiplier-extension ,floating-point-multiplicand ,integer-portion ,fractional-portion 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments floating-point-multiplier OpenVMS usage:floating_point type: IEEE S_floating access: read only mechanism: by reference The multiplier. The floating-point-multiplier argument is the address of an IEEE S-floating number containing the number. multiplier-extension OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference The left-justified multiplier-extension bits. The multiplier- extension argument is the address of an unsigned byte containing these multiplier extension bits. floating-point-multiplicand OpenVMS usage:floating_point type: IEEE S_floating access: read only mechanism: by reference The multiplicand. The floating-point-multiplicand argument is an IEEE S-floating number. integer-portion OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference The integer portion of the result. The integer-portion argument is the address of a signed longword integer containing the integer portion of the result. fractional-portion OpenVMS usage:floating_point type: IEEE S_floating access: write only mechanism: by reference The fractional portion of the result. The fractional-portion argument is the address of an IEEE S-floating number containing the fractional portion of the result. 3 LIB$EMODT (Alpha and i64 only.) The Extended Multiply and Integerize routine (IEEE T-Floating-Point Values) allows higher-level language users to perform accurate range reduction of IEEE T- floating arguments. Format LIB$EMODT floating-point-multiplier ,multiplier-extension ,floating-point-multiplicand ,integer-portion ,fractional-portion 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments floating-point-multiplier OpenVMS usage:floating_point type: IEEE T_floating access: read only mechanism: by reference The multiplier. The floating-point-multiplier argument is the address of an IEEE T-floating number containing the number. multiplier-extension OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference The left-justified multiplier-extension bits. The multiplier- extension argument is the address of an unsigned byte containing these multiplier extension bits. floating-point-multiplicand OpenVMS usage:floating_point type: IEEE T_floating access: read only mechanism: by reference The multiplicand. The floating-point-multiplicand argument is an IEEE T-floating number. integer-portion OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference The integer portion of the result. The integer-portion argument is the address of a signed longword integer containing the integer portion of the result. fractional-portion OpenVMS usage:floating_point type: IEEE T_floating access: write only mechanism: by reference The fractional portion of the result. The fractional-portion argument is the address of an IEEE T-floating number containing the fractional portion of the result. 3 LIB$EMUL The Extended-Precision Multiply routine performs extended- precision multiplication. LIB$EMUL makes the VAX EMUL instruction available as a callable routine. Format LIB$EMUL longword-integer-multiplier ,longword-integer-multiplicand ,addend ,product 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments longword-integer-multiplier OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Multiplier used by LIB$EMUL in the extended-precision multiplication. The longword-integer-multiplier argument is the address of a signed longword integer containing the multiplier. longword-integer-multiplicand OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Multiplicand used by LIB$EMUL in the extended-precision multiplication. The longword-integer-multiplicand argument is the address of a signed longword integer containing the multiplicand. addend OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Addend used by LIB$EMUL in the extended-precision multiplication. The addend argument is the address of a signed longword integer containing the addend. product OpenVMS usage:quadword_signed type: quadword integer (signed) access: write only mechanism: by reference Product of the extended-precision multiplication. The product argument is the address of a signed quadword integer into which LIB$EMUL writes the product. 3 LIB$ENABLE_CTRL The Enable CLI Interception of Control Characters routine requests the calling process's command language interpreter (CLI) to resume interception of the selected control characters when they are typed during an interactive terminal session. LIB$ENABLE_CTRL provides the same function as the DCL command SET CONTROL. Format LIB$ENABLE_CTRL enable-mask [,old-mask] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments enable-mask OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask indicating for which control characters LIB$ENABLE_ CTRL is to enable interception. The enable-mask argument is the address of an unsigned longword containing this bit mask. Each of the 32 bits corresponds to one of the 32 possible control characters. If a bit is set, the corresponding control character is intercepted by the CLI. Currently, only bits 20 and 25, corresponding to Ctrl/T and Ctrl/Y, are recognized. The following mask is defined in symbol libraries supplied by HP to specify the value of enable-mask: Symbol Hex Value Function LIB$M_CLI_ %X'00100000' Enables Ctrl/T CTRLT LIB$M_CLI_ %X'02000000' Enables Ctrl/Y CTRLY If a set bit does not correspond to a character that the CLI can intercept, an error is returned. old-mask OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Previous bit mask. The old-mask argument is the address of an unsigned longword containing the old bit mask. The old bit mask is of the same form as enable-mask. 3 LIB$ESTABLISH The Establish a Condition Handler routine moves the address of a condition handling routine (which can be a user-written or a library routine) to longword 0 of the stack frame of the caller of LIB$ESTABLISH. This routine is not available to native OpenVMS Alpha and I64 programs but is recognized and handled appropriately by most HP high-level language compilers. Format LIB$ESTABLISH new-handler 4 Returns OpenVMS usage:routine type: procedure value access: write only mechanism: by reference Previous contents of SF$A_HANDLER (longword 0) of the caller's stack frame; zero if no handler existed. 4 Argument new-handler OpenVMS usage:procedure type: procedure value access: read only mechanism: by value Routine to be set up as the condition handler. The new-handler argument is the address of the procedure value to this routine. 3 LIB$EXPAND_NODENAME The Expand a Node Name to Its Full Name Equivalent routine expands a node name to its full name equivalent. Format LIB$EXPAND_NODENAME nodename, fullname [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments nodename OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Node name to be expanded. 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 nodename is an invalid descriptor. fullname OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Expanded node name. The fullname argument contains the address of a descriptor pointing to the expanded node-name string. LIB$EXPAND_NODENAME writes the expanded node-name string into the buffer pointed to by the fullname descriptor. The error LIB$_INVSTRDES is returned if fullname is an invalid descriptor. The length field of the fullname descriptor is not updated unless fullname is a dynamic descriptor with a length less than the resulting expanded full name. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage. The fullname argument contains an unusable result when LIB$EXPAND_NODENAME returns in error. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the expanded 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$EXPAND_NODENAME returns in error. 3 LIB$EXTV The Extract a Field and Sign-Extend routine returns a sign- extended longword field that has been extracted from the specified variable bit field. LIB$EXTV makes the VAX EXTV instruction available as a callable routine. Format LIB$EXTV position ,size ,base-address 4 Returns OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by value Field extracted by LIB$EXTV, sign-extended to a longword. 4 Arguments position OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Position (relative to the base address) of the first bit in the field that LIB$EXTV extracts. The position argument is the address of a signed longword integer containing the position. size OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Size of the bit field LIB$EXTV extracts. The size argument is the address of an unsigned byte containing the size. The maximum size is 32 bits. base-address OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Base address of the bit field LIB$EXTV extracts from the specified variable bit field. The base-address argument is an unsigned longword containing the base address. 3 LIB$EXTZV The Extract a Zero-Extended Field routine returns a longword zero-extended field that has been extracted from the specified variable bit field. LIB$EXTZV makes the VAX EXTZV instruction available as a callable routine. Format LIB$EXTZV position ,size ,base-address 4 Returns OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by value Field extracted by LIB$EXTZV, zero-extended to a longword. 4 Arguments position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Position (relative to the base address) of the first bit in the field LIB$EXTZV extracts. The position argument is the address of a signed longword integer containing the position. size OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Size of the bit field LIB$EXTZV extracts. The size argument is the address of an unsigned byte containing the size. The maximum size is 32 bits. base-address OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Base address of the bit field LIB$EXTZV extracts. The base- address argument is an unsigned longword containing the base address. 3 LIB$FFx The Find First Clear or Set Bit routines search the field specified by the start position, size, and base for the first clear or set bit. LIB$FFC and LIB$FFS make the VAX FFC and VAX FFS instructions available as callable routines. Format LIB$FFC position ,size ,base ,find-position LIB$FFS position ,size ,base ,find-position 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments position OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Starting position, relative to the base address, of the bit field to be searched by LIB$FFx. The position argument is the address of a signed longword integer containing the starting position. size OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Number of bits to be searched by LIB$FFx. The size argument is the address of an unsigned byte containing the size of the bit field to be searched. The maximum size is 32 bits. base OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference The base argument is the address of the bit field that LIB$FFx searches. find-position OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Bit position of the first bit in the specified state (clear or set), relative to the base address. The find-position argument is the address of a signed longword integer into which LIB$FFC writes the position of the first clear bit and into which LIB$FFS writes the position of the first set bit. 3 LIB$FID_TO_NAME The Convert Device and File ID to File Specification routine converts a disk device name and file identifier to a file specification. Format LIB$FID_TO_NAME device-name ,file-id ,filespec [,filespec-length] [,directory-id] [,acp-status] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments device-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Device name to be converted. The device-name argument is the address of a descriptor pointing to the device name. It must reference a disk device, and must contain 64 characters or less. LIB$FID_TO_NAME obtains device-name from the NAM$T_DVI field of an OpenVMS RMS name block. file-id OpenVMS usage:vector_word_unsigned type: word (unsigned) access: read only mechanism: by reference, array reference Specifies the file identifier. The file-id argument is the address of an array of three words containing the file identification. LIB$FID_TO_NAME obtains file-id from the NAM$W_ FID field of an OpenVMS RMS name block. The $FIDDEF macro defines the structure of file-id. filespec OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the file specification. The filespec argument is the address of a descriptor pointing to the file specification string. As of OpenVMS Version 7.2, the maximum file specification string that can be returned is 4095 bytes on Alpha and I64 systems, and 510 bytes on VAX systems. On versions prior to Version 7.2, the maximum is 510 bytes on both platforms. filespec-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Receives the number of characters written into filespec, excluding padding in the case of a fixed-length string. The optional filespec-length argument is the address of an unsigned word containing the number of characters. If the output string is truncated to the number of characters specified in filespec, then filespec-length is set to that truncated size. Therefore, you can always use filespec-length to access a valid substring of filespec. directory-id OpenVMS usage:vector_word_unsigned type: word (unsigned) access: read only mechanism: by reference, array reference Specifies a directory file identifier. The directory-id argument is the address of an array of three words containing the directory file identifier. LIB$FID_TO_NAME obtains this array from the NAM$W_DID field of an OpenVMS RMS name block. The $FIDDEF macro defines the structure of directory-id. This parameter is relevant only for a structure level-1 disk on OpenVMS VAX systems. This parameter is ignored on OpenVMS Alpha and I64 systems because level-1 disks are not supported on OpenVMS Alpha and I64 systems. acp-status OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference The status resulting from traversing the backward links. The optional acp-status argument is the address of an unsigned longword containing the status. 3 LIB$FILE_SCAN The File Scan routine searches an area, such as a directory, for all files matching the file specification given and transfers program execution to the specified user-written routine. Wildcards are acceptable. An action routine is called for each file and/or error found. LIB$FILE_SCAN allows the search sequence to continue even if an error occurs while processing a particular file. Format LIB$FILE_SCAN fab ,user-success-procedure ,user-error-procedure [,context] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fab OpenVMS usage:fab type: unspecified access: read only mechanism: by reference File Access Block (FAB) referencing a valid NAM block or NAML block. The fab argument is the address of the FAB that contains the address and length of the file specification being searched for by LIB$FILE_SCAN. On Alpha and I64 systems, NAML blocks support the use of file specifications with a maximum length of NAML$C_MAXRSS. See the OpenVMS Record Management Services Reference Manual for information on NAML blocks. user-success-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied success routine that LIB$FILE_SCAN calls when a file is found. The success routine is invoked with the FAB address that was passed to LIB$FILE_SCAN. The user context may be pased to this routine using the FAB$L_CTX field in the FAB. user-error-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied error routine that LIB$FILE_SCAN calls when it encounters an error. The error routine is called with the FAB argument that was passed to LIB$FILE_SCAN. context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Default file context used in processing file specifications for multiple input files. The context argument is the address of a longword, which must be initialized to zero by your program before the first call to LIB$FILE_SCAN. After the first call, LIB$FILE_SCAN maintains this longword. You must not change the value of context in subsequent calls to LIB$FILE_SCAN. Name blocks and file specification strings are allocated by LIB$FILE_SCAN, and context is used to retain their addresses so they may be deallocated later. If the context argument is not passed, unspecified portions of the file specification will be inherited from the previous file specification processed, rather than from multiple input file specifications. 3 LIB$FILE_SCAN_END The End-of-File Scan routine is called after each sequence of calls to LIB$FILE_SCAN. LIB$FILE_SCAN_END deallocates any saved OpenVMS RMS context and/or deallocates the virtual memory that had been allocated for holding the related file specification information. Format LIB$FILE_SCAN_END [fab] [,context] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fab OpenVMS usage:fab type: unspecified access: modify mechanism: by reference File access block (FAB) used with LIB$FILE_SCAN. The optional fab argument is the address of the FAB that contains the address and length of the file specification. context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Temporary default context used in LIB$FILE_SCAN. The optional context argument is the address of a longword containing this temporary default context. 3 LIB$FIND_FILE The Find File routine is called with a file specification for which it searches. LIB$FIND_FILE returns one file specification for each call. The file specification may contain wildcards. Format LIB$FIND_FILE filespec ,resultant-filespec ,context [,default-filespec] [,related-filespec] [,status-value] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification, which may contain wildcards, that LIB$FIND_ FILE uses to search for the desired file. The filespec argument is the address of a descriptor pointing to the file specification. If running on Alpha or I64 and flag LIB$M_FIL_ LONG_NAMES is set, the maximum length of a file specification is specified by NAML$C_MAXRSS, otherwise the maximum length of a file specification is 255 bytes. The file specification used may also contain a search list logical name. If present, the search list logical name elements can be used as accumulative to related file specifications, so that portions of file specifications not specified by the user are inherited from previous file specifications. resultant-filespec OpenVMS usage:char_string type: character string access: modify mechanism: by descriptor Resultant file specification that LIB$FIND_FILE returns when it finds a file that matches the specification in the filespec argument. The resultant-filespec argument is the address of a descriptor pointing to the resultant file specification. context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference A longword integer variable into which the routine stores a context value for use by future calls to LIB$FIND_FILE or LIB$FIND_FILE_END. The context argument is an unsigned longword integer containing the address of the context. This variable must be set to zero before the first call to LIB$FIND_FILE. You can use the same context argument from one LIB$FIND_FILE call to another provided you have not called LIB$FIND_FILE_END for that context first. LIB$FIND_FILE uses this argument to retain the context when processing multiple input files. Portions of file specifications that the user does not specify may be inherited from the last files processed because the file contexts are retained in this argument. You must not change the value of context in subsequent calls to LIB$FIND_FILE. default-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Default file specification. The default-filespec argument is the address of a descriptor pointing to the default file specification. See the OpenVMS Record Management Services Reference Manual for information about default file specifications. related-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Related file specification containing the context of the last file processed. The related-filespec argument is the address of a descriptor pointing to the related file specification. The related file specification is useful when you are processing lists of file specifications. Unspecified portions of the file specification are inherited from the last file processed. For more information on related file specifications, see the OpenVMS Record Management Services Reference Manual. status-value OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference RMS secondary status value from a failing RMS operation. The status-value argument is an unsigned longword containing the address of a longword-length buffer to receive the RMS secondary status value (usually returned in the file access block field, FAB$L_STV). flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference User flags. The flags argument is the address of an unsigned longword containing the user flags. The flag bits and their corresponding symbols are described in the following table: Bit Symbol Description 0 LIB$M_FIL_NOWILD If set, LIB$FIND_FILE returns an error if a wildcard character is input. 1 LIB$M_FIL_ If set, this performs temporary MULTIPLE defaulting for multiple input files and the related-filespec argument is ignored. See description of context in LIB$FILE_SCAN. Each time LIB$FIND_ FILE is called with a different file specification, the specification from the previous call is automatically used as a related file specification. This allows parsing of the elements of a search- list logical name such as DISK2:[SMITH] FIL1.TYP,FIL*2.TYP, and so on. Use of this feature is required to get the desired defaulting with search list logical name. LIB$FIND_FILE_END must be called between each command line in interactive use or the defaults from the previous command line affect the current file specification. 2 LIB$M_FIL_LONG_ (Alpha and I64 only) If set, LIB$FIND_ NAMES FILE can process file specifications with a maximum length of NAML$C_MAXRSS. If clear, LIB$FIND_FILE can process file specifications with a maximum length of 255 (default). 3 LIB$FIND_FILE_END The End of Find File routine is called once after each sequence of calls to LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any saved OpenVMS RMS context and deallocates the virtual memory used to hold the allocated context block. Format LIB$FIND_FILE_END context 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument context OpenVMS usage:context type: longword (unsigned) access: read only mechanism: by reference Zero or the address of a FAB/NAM buffer from a previous call to LIB$FIND_FILE. The context argument is the address of a longword that contains this context. 3 LIB$FIND_IMAGE_SYMBOL The Find Universal Symbol in Shareable Image File routine reads universal symbols from the shareable image file. This routine then dynamically activates a shareable image into the P0 address space of a process. Format LIB$FIND_IMAGE_SYMBOL filename ,symbol ,symbol-value [,image-name] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments filename OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the file for which LIB$FIND_IMAGE_SYMBOL is searching. The filename argument is the address of a descriptor pointing to this file name string. This argument may contain only the file name. File type cannot be indicated. If any file specification punctuation characters (:, [, <, ;, .) are present, the error SS$_IVLOGNAM is returned. You can specify a file specification for the image name with the optional image-name argument. If you do not specify image-name, a default file specification of SYS$SHARE:.EXE is applied to the file name. If the file is not in SYS$SHARE:.EXE, a logical name must be used to direct this routine to locate the correct file. Only logical names defined in the system logical name table with the /EXEC attribute will be considered while the image activator is processing a request from an image that was installed with privileges. If the calling image was installed with privileges, the image being activated and any shareable images or message sections it references must be installed as a known image with the INSTALL utility. Running an image to which you have only Execute (not Read) access results in the same restrictions on logical names and shareable images as does running a privileged image. On VAX systems, the filename descriptor must be class D, S, or Z. symbol OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Symbol for which LIB$FIND_IMAGE_SYMBOL is searching in the filename file. The symbol argument is the address of a descriptor pointing to the symbol name string. The symbol name string can be input in uppercase, lowercase, or mixed case letters. symbol-value OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Symbol value that LIB$FIND_IMAGE_SYMBOL has located. The symbol- value argument is the address of a signed longword integer into which LIB$FIND_IMAGE_SYMBOL returns the symbol value. If the symbol is relocatable, the starting virtual address of the shareable image in memory is added to the symbol value. image-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Default file specification applied to the image name. The optional image-name argument is a string used as the RMS default file specification when parsing filename as the primary filename. If image-name is not supplied, then a default file specification of SYS$SHARE:.EXE is applied to the image name. On VAX systems, the image-name descriptor must be class D, S, or Z. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value Control flags. The flags argument is the address of a longword integer that contains the control flags. Bit Value Description 0 Reserved to HP 1 Reserved to HP 2 Reserved to HP 3 Reserved to HP 4 LIB$M_FIS_MIXEDCASE Causes LIB$FIND_IMAGE_SYMBOL to look for the symbol without converting it to uppercase. This is an optional argument. If omitted, the default is 0. If omitted, or if LIB$M_FIS_MIXEDCASE (bit 4) is 0, LIB$FIND_IMAGE_ SYMBOL converts the specified symbol to uppercase before it is used. 3 LIB$FIND_VM_ZONE The Return the Next Valid Zone Identifier routine returns the zone identifier of the next valid zone in the heap management 32-bit database. Format LIB$FIND_VM_ZONE context ,zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context specifier. The context argument is the address of an unsigned longword used to keep the scan context for finding the next valid zone. The context argument must be 0 to initialize the scan and to start with the first returnable zone identifier. zone-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Zone identifier. The zone-id argument is the address of an unsigned longword that receives the zone identifier for the next zone. 3 LIB$FIND_VM_ZONE_64 (Alpha and I64 only.) The Return the Next Valid Zone Identifier routine returns the zone identifier of the next valid zone in the heap management 64-bit database. Format LIB$FIND_VM_ZONE_64 context ,zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments context OpenVMS usage:context type: quadword (unsigned) access: modify mechanism: by reference Context specifier. The context argument is the address of an unsigned quadword used to keep the scan context for finding the next valid zone. The context argument must be 0 to initialize the scan and to start with the first returnable zone identifier. zone-id OpenVMS usage:identifier type: quadword (unsigned) access: write only mechanism: by reference Zone identifier. The zone-id argument is the address of an unsigned quadword that receives the zone identifier for the next zone. 3 LIB$FIT_NODENAME The Fit a Node Name Into an Output Field routine fits a node name into an output field. It attempts to compress the node name to fit the output field. If this fails, it trims the node name. Format LIB$FIT_NODENAME nodename, output-buffer [,output-width][,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments nodename OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Node name to be fitted into the desired output field. 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 nodename is an invalid descriptor. output-buffer OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor The output buffer. The output-buffer argument contains the address of a descriptor pointing to the output buffer. LIB$FIT_ NODENAME writes the final output node name into the buffer pointed to by output-buffer. The error LIB$_INVSTRDES is returned if output-buffer is an invalid descriptor. The length field of the output-buffer descriptor is not updated unless output-buffer is a dynamic descriptor with a length less than the resulting fitted node name. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage. The output-buffer argument contains an unusable result when LIB$FIT_NODENAME returns in error. output-width OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Field width desired for the fit operation. The output-width argument is the address of an unsigned word that contains this field width in bytes. If output-width is omitted, the current length of output-buffer is used. If output-buffer is not a fixed-length string, specify output-width to ensure that the desired width is used. If the lengths of both output-buffer and output-width are specified, the length in output-width is used. In this case, if the current length of output-buffer is smaller than the length of output-width, the output node name is truncated at the end, and the alternate successful status LIB$_STRTRU is returned. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the output 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$FIT_NODENAME returns in error. 3 LIB$FIXUP_FLT The Fix Floating Reserved Operand routine finds the reserved operand of any F-floating, D-floating, G-floating, or H-floating instruction (with some exceptions) after a reserved operand fault has been signaled. LIB$FIXUP_FLT changes the reserved operand from -0.0 to the value of the new-operand argument, if present; or to +0.0 if new-operand is absent. This routine is available on OpenVMS Alpha and I64 systems in translated form and is applicable to translated VAX images only. Format LIB$FIXUP_FLT signal-arguments ,mechanism-arguments [,new-operand] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments signal-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference Signal argument vector. The signal-arguments argument is the address of an array of unsigned longwords containing the signal argument vector. mechanism-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference Mechanism argument vector. The mechanism-arguments argument is the address of an array of unsigned longwords containing the mechanism argument vector. new-operand OpenVMS usage:floating-point type: F_floating access: read only mechanism: by reference An F-floating value to replace the reserved operand. The new-operand argument is the address of an F-floating number containing the new operand. This is an optional argument. If omitted, the default value is +0.0. 3 LIB$FLT_UNDER The Floating-Point Underflow Detection routine enables or disables floating-point underflow detection for the calling routine activation. The previous setting is returned as a function value. This routine is available on OpenVMS Alpha and I64 systems in translated form and is applicable to translated VAX images only. Format LIB$FLT_UNDER new-setting 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The old floating-point underflow enable setting (the previous contents of the SF$W_PSW[PSW$V_FU] in the caller's frame). 4 Argument new-setting OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference New floating-point underflow enable setting. The new-setting argument is the address of an unsigned byte containing the new setting. Bit 0 set to 1 means enable; bit 0 set to 0 means disable. 3 LIB$FORMAT_DATE_TIME The Format Date and/or Time routine allows the user to select at run time a specific output language and format for a date or time, or both. Format LIB$FORMAT_DATE_TIME date-string [,date] [,user-context] [,date-length] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments date-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the requested date or time, or both, that has been formatted for output according to the currently selected format and language. The date-string argument is the address of a descriptor pointing to this string. date OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference The date or time, or both, to be formatted for output. The date argument is the address of an unsigned quadword that contains the absolute date or time, or both to be formatted. If you omit this argument, or if you supply a zero passed by value, then the current system time is used. Note that the date argument must represent an absolute time, not a delta time. user-context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context that retains the translation context over multiple calls to this routine. The user-context argument is the address of an unsigned longword that contains this context. The initial value of the context variable must be zero. Thereafter, the user program must not write to the cell. The user-context parameter is optional. However, if a context cell is not passed, the routine LIB$FORMAT_DATE_TIME 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, HP recommends that users specify a different context cell for each calling thread. date-length OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Number of bytes of text written to the date-string argument. The date-length argument is the address of a signed longword that receives this string length. Note that date-length specifies the number of bytes of text, not the number of characters, written to date-string. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that allows the user to specify whether the date, time, or both are output. The flags argument is the address of an unsigned bit mask containing the specified values. Valid values are LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS. Default values are determined as follows: o If the flags argument is omitted, LIB$FORMAT_DATE_TIME determines which fields to format according to the current definition of LIB$DT_FORMAT. o If the flags argument is specified, LIB$FORMAT_DATE_TIME uses the flags value to determine which fields to format. That is, the flags argument can be used to override the definition of LIB$DT_FORMAT when specifying which fields should be formatted for output. If the field specified by flags was not assigned a format through the definition of LIB$DT_FORMAT, the standard OpenVMS format is used. 3 LIB$FORMAT_SOGW_PROT The Format Protection Mask routine translates a protection mask into a formatted string. Format LIB$FORMAT_SOGW_PROT protection-mask, [access-names], [ownership-names], [ownership-separator], [list-separator], protection-string, [protection-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments protection-mask OpenVMS usage:protection type: word (unsigned) access: read only mechanism: by reference The address of a word that holds a 16-bit protection mask to be translated. access-names OpenVMS usage:access_names type: array [0..31] of quadword string descriptor access: read only mechanism: by reference The address of the access name table for the associated object class. For example, it is the value returned in accnam by LIB$GET_ACCNAM. This parameter defaults to the access name table for the FILE object class. ownership-names OpenVMS usage:char_string type: array [0..3] of quadword string descriptor access: read only mechanism: by reference The address of a vector of 4 quadword descriptors that points to the ownership name. The default value is the full ownership category names (System, Owner, Group, World). ownership-separator OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor The address of a descriptor that points to the ownership separator string. The separator string is inserted after the ownership name to introduce a nonempty set of access names. By default, the value is ": " (the colon and space characters). list-separator OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor The address of a descriptor that points to the list separator string. The list separator string is inserted between ownership- access type pairs. By default, the value is ", " (the comma and space characters). protection-string OpenVMS usage:char_string type: character-coded text string access: write only mechanism: by descriptor The address of a character-string descriptor that receives the output of the routine call. The protection-string argument points to the formatted protection string at the end of a call. The protection string has the following components repeated for each of: System, Owner, Group, World: ownership-name[ownership-separator][access-types][list-separator] An example of a formatted protection string is System: RWED, Owner: RWED, Group: RW, World: R protection-length OpenVMS usage:word_signed type: word (signed) access: write only mechanism: by reference The address of a word that receives the length of the string returned in the protection-string argument. 3 LIB$FREE_DATE_TIME_CONTEXT The Free the Context Area Used When Formatting Dates and Times for Input or Output routine frees the virtual memory associated with the context area used by the date/time input and output formatting routines. Format LIB$FREE_DATE_TIME_CONTEXT [user-context] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument user-context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context that retains the translation context over multiple calls to the date/time input and output formatting routines. The user-context argument is the address of an unsigned longword that contains this context. If the user-context argument was not specified in the call to LIB$FORMAT_DATE_TIME, LIB$CONVERT_DATE_ STRING, or LIB$GET_MAXIMUM_DATE_LENGTH, then no argument should be supplied when calling this routine. 3 LIB$FREE_EF The Free Event Flag routine frees a local event flag previously allocated by LIB$GET_EF or by LIB$RESERVE_EF. LIB$FREE_EF is the complement of LIB$GET_EF. Format LIB$FREE_EF event-flag-number 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument event-flag-number OpenVMS usage:ef_number type: longword integer (unsigned) access: read only mechanism: by reference Event flag number to be deallocated by LIB$FREE_EF. The event- flag-number argument is the address of a signed longword integer that contains the event flag number, which is the value allocated to the user by LIB$GET_EF or LIB$RESERVE_EF. 3 LIB$FREE_LUN The Free Logical Unit Number routine releases a logical unit number allocated by LIB$GET_LUN to the pool of available numbers. LIB$FREE_LUN is the complement of LIB$GET_LUN. Format LIB$FREE_LUN logical-unit-number 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument logical-unit-number OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Logical unit number to be deallocated. The logical-unit-number argument is the address of a signed longword integer that contains this logical unit number, which is the value previously returned by LIB$GET_LUN. 3 LIB$FREE_TIMER The Free Timer Storage routine frees the storage allocated by LIB$INIT_TIMER. Format LIB$FREE_TIMER handle-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument handle-address OpenVMS usage:address type: longword (unsigned) access: modify mechanism: by reference Pointer to a block of storage containing the value returned by a previous call to LIB$INIT_TIMER; this is the storage that LIB$FREE_TIMER deallocates. The handle-address argument is the address of an unsigned longword containing that value. 3 LIB$FREE_VM The Free Virtual Memory from Program Region routine deallocates an entire block of contiguous bytes that was allocated by a previous call to LIB$GET_VM. The arguments passed are the same as for LIB$GET_VM. Format LIB$FREE_VM number-of-bytes ,base-address [,zone-id] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-bytes OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Number of contiguous bytes to be deallocated by LIB$FREE_VM. The number-of-bytes argument is the address of a signed longword integer that contains this number. The value of number-of-bytes must be greater than zero. Byte counts are rounded in the same manner as in LIB$GET_VM. NOTE You may omit the number-of-bytes argument if you are using boundary tags (LIB$M_VM_BOUNDARY_TAGS). base-address OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Address of the first byte to be deallocated by LIB$FREE_VM. The base-address argument contains the address of an unsigned longword that is this address. The value of base-address must be the address of a block of memory that was allocated by a previous call to LIB$GET_VM. zone-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference The address of a longword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ ZONE. You must specify the same zone-id value as when you called LIB$GET_VM to allocate the block. An error status will be returned if you specify an incorrect zone-id. The zone-id argument is optional. If zone-id is omitted or if the longword contains the value 0, the 32-bit default zone is used. 3 LIB$FREE_VM_64 (Alpha and I64 only.) The Free Virtual Memory from Program Region routine deallocates an entire block of contiguous bytes that was allocated by a previous call to LIB$GET_VM_64. The arguments passed are the same as for LIB$GET_VM_64. Format LIB$FREE_VM_64 number-of-bytes ,base-address [,zone-id] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-bytes OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Number of contiguous bytes to be deallocated by LIB$FREE_VM_64. The number-of-bytes argument is the address of a signed quadword integer that contains this number. The value of number-of-bytes must be greater than zero. Byte counts are rounded in the same manner as in LIB$GET_VM_64. NOTE You may omit the number-of-bytes argument if you are using boundary tags (LIB$M_VM_BOUNDARY_TAGS). base-address OpenVMS usage:address type: quadword (unsigned) access: read only mechanism: by reference Address of the first byte to be deallocated by LIB$FREE_VM_64. The base-address argument contains the address of an unsigned quadword that is this address. The value of base-address must be the address of a block of memory that was allocated by a previous call to LIB$GET_VM_64. zone-id OpenVMS usage:identifier type: quadword (unsigned) access: read only mechanism: by reference The address of a quadword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_ VM_ZONE_64. You must specify the same zone-id value as when you called LIB$GET_VM_64 to allocate the block. An error status will be returned if you specify an incorrect zone-id. The zone-id argument is optional. If zone-id is omitted or if the quadword contains the value 0, the 64-bit default zone is used. 3 LIB$FREE_VM_PAGE The Free Virtual Memory Page routine deallocates a block of contiguous pages on VAX systems or pagelets on Alpha and I64 systems that were allocated by previous calls to LIB$GET_VM_PAGE. Format LIB$FREE_VM_PAGE number-of-pages ,base-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-pages OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Number of pages on VAX systems or pagelets on Alpha and I64 systems. The number-of-pages argument is the address of a longword integer that specifies the number of contiguous pages on VAX systems or pagelets on Alpha and I64 systems to be deallocated. The value of number-of-pages must be greater than zero. base-address OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Block address. The base-address argument is the address of a longword that contains the address of the first byte of the first VAX page or Alpha or I64 pagelet to be deallocated. 3 LIB$FREE_VM_PAGE_64 (Alpha and I64 only.) The Free Virtual Memory Page routine deallocates a block of contiguous Alpha or I64 pagelets that was allocated by previous calls to LIB$GET_VM_PAGE_64. Format LIB$FREE_VM_PAGE_64 number-of-pages ,base-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-pages OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Number of Alpha or I64 pagelets. The address of a quadword integer that specifies the number of contiguous Alpha or I64 pagelets to be deallocated. The value of number-of-pages must be greater than zero. base-address OpenVMS usage:address type: quadword (unsigned) access: read only mechanism: by reference Block address. The base-address argument is the address of a quadword that contains the address of the first byte of the first Alpha or I64 pagelet to be deallocated. 3 LIB$GETDVI The Get Device/Volume Information routine provides a simplified interface to the $GETDVI system service. It returns information about the primary and secondary device characteristics of an I/O device. The calling process need not have a channel assigned to the device about which it wants information. Format LIB$GETDVI item-code [,channel] [,device-name] [,longword-integer-value] [,resultant-string] [,resultant-length] [,pathname] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments item-code OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Code specifying the item of information you are requesting. The item-code argument is the address of a signed longword containing the item code. All valid $GETDVI item codes whose names begin with DVI$_ are accepted. channel OpenVMS usage:channel type: word (unsigned) access: read only mechanism: by reference OpenVMS I/O channel assigned to the device for which LIB$GETDVI returns information. The channel argument is the address of an unsigned word containing the channel specification. If channel is not specified, device-name is used instead. You must specify either channel or device-name, but not both. If neither is specified, the error status SS$_IVDEVNAM is returned. device-name OpenVMS usage:device_name type: character string access: read only mechanism: by descriptor Name of the device for which LIB$GETDVI returns information. The device-name argument is the address of a descriptor pointing to the device name string. If this string contains a colon, the colon and the characters that follow it are ignored. The device-name may be either a physical device name or a logical name. If the first character in the string is an underscore character (_), the name is considered a physical device name. Otherwise, the name is considered a logical name, and logical name translation is performed until either a physical device name is found or the system default number of translations has been performed. If device-name is not specified, channel is used instead. You must specify either channel or device-name, but not both. If neither is specified, the error status SS$_IVDEVNAM is returned. The device name must not be longer than 255 characters. longword-integer-value OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Numeric value of the information requested. The longword-integer- value argument is the address of a signed longword containing the numeric value. If an item is listed as only returning a string value, this argument is ignored. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String representation of the information requested. The resultant-string argument is the address of a descriptor pointing to this information. If resultant-string is not specified and if the value returned has only a string representation, the error status LIB$_INVARG is returned. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of significant characters written to resultant-string by LIB$GETDVI. The resultant-length argument is the address of an unsigned word containing this length. pathname OpenVMS usage:path_name type: character text string access: read only mechanism: by descriptor (I64 and Alpha only) The name of the path about which $GETDVI is to return information. The pathname argument is the address of a character string descriptor pointing to this name string. The path name may be used with either the channel or device-name arguments. Check the definitions of the item codes to see if the pathname argument is used. In general, item codes that return information that may vary by path will make use of the pathname argument. The paths for a multipath device can be seen with the SHOW DEVICE /FULL command, the SYS$DEVICE_PATH_SCAN system service, or the F$MULTIPATH DCL lexical function. If the pathname argument is used, it will be validated against the existing paths for the device specified. If the path does not exist, the error SS$_NOSUCHPATH will be returned, even if the item codes(s) used do not make use of the pathname argument. 3 LIB$GETJPI The Get Job/Process Information routine provides a simplified interface to the $GETJPI system service. It provides accounting, status, and identification information about a specified process. LIB$GETJPI obtains only one item of information in a single call. Format LIB$GETJPI item-code [,process-id] [,process-name] [,resultant-value] [,resultant-string] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments item-code OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Item identifier code specifying the item of information you are requesting. The item-code argument is the address of a signed longword containing the item code. You may request only one item in each call to LIB$GETJPI. LIB$GETJPI accepts all $GETJPI item codes. These names begin with JPI$_ and are defined in symbol libraries in module $JPIDEF supplied by HP. process-id OpenVMS usage:process_id type: longword (unsigned) access: modify mechanism: by reference Process identifier of the process for which you are requesting information. The process-id argument is the address of an unsigned longword containing the process identifier. If you do not specify process-id, process-name is used. The process-id is updated to contain the process identifier actually used, which may be different from what you originally requested if you specified process-name or used wildcard process searching. process-name OpenVMS usage:process_name type: character string access: read only mechanism: by descriptor A 1- to 15-character string specifying the name of the process for which you are requesting information. The process-name argument is the address of a descriptor pointing to the process name string. The name must correspond exactly to the name of the process for which you are requesting information; LIB$GETJPI does not allow trailing blanks or abbreviations. If you do not specify process-name, process-id is used. If you specify neither process-name nor process-id, the caller's process is used. Also, if you do not specify process-name and you specify zero for process-id, the caller's process is used. In this way, you can fetch the item you want and the caller's PID in a single call to LIB$GETJPI. resultant-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Numeric value of the information you request. The resultant-value argument is the address of a longword or quadword into which LIB$GETJPI writes the numeric value of this information. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String representation of the information you request. The resultant-string argument is the address of the descriptor for a character string into which LIB$GETJPI writes the string representation. If you do not include resultant-string, but the item you request has only a string representation, the error status LIB$_INVARG is returned. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of significant characters written to resultant-string by LIB$GETJPI. The resultant-length argument is the address of an unsigned word integer into which LIB$GETJPI writes the number of characters. 3 LIB$GETQUI The Get Queue Information routine provides a simplified interface to the $GETQUI system service. It provides queue, job, file, characteristic, and form information about a specified process. LIB$GETQUI obtains only one item of information in a single call. Format LIB$GETQUI function-code [,item-code] [,search-number] [,search-name] [,search-flags] [,resultant-value] [,resultant-string] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments function-code OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Function code specifying the function that LIB$GETQUI is to perform. The function-code argument is the address of a signed longword containing the function code. LIB$GETQUI accepts all $GETQUI function codes. These names begin with QUI$_ and are defined in symbol libraries in module $QUIDEF supplied by HP. item-code OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Item identifier code specifying the item of information you are requesting. The item-code argument is the address of a signed longword containing the item code. You may request only one item in each call to LIB$GETQUI. LIB$GETQUI accepts all $GETQUI item codes. These names begin with QUI$_ and are defined in symbol libraries in module $QUIDEF supplied by HP. search-number OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Numeric value used to process your request. The search-number argument is the address of a signed longword integer containing the number needed to process your request. The search-number argument corresponds directly to QUI$_SEARCH_NUMBER as described by the $GETQUI system service. search-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Character string used to process your request. The search-name argument is the address of a string descriptor that provides the name needed to process your request. The search-name argument corresponds directly to QUI$_SEARCH_NAME as described by the $GETQUI system service. search-flags OpenVMS usage:longword_unsigned type: longword integer (unsigned) access: read only mechanism: by reference Optional bit mask indicating request to be performed. The search- flags argument is the address of an unsigned longword integer containing the bit mask. The search-flags argument directly corresponds to $QUI_SEARCH_FLAGS as described by the $GETQUI system service. resultant-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Numeric value of the information you requested. The resultant- value argument is the address of a longword, quadword or octaword into which LIB$GETQUI writes the numeric value of this information. If the item you requested returns only a string value, this argument is ignored. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String representation of the information you requested. The resultant-string argument is the address of the descriptor for a character string into which LIB$GETQUI writes the string representation. If you do not include resultant-string, but the item you request has only a string representation, the error status LIB$_INVARG is returned. resultant-length OpenVMS usage:word_signed type: word integer (signed) access: write only mechanism: by reference Number of significant characters written to resultant-string by LIB$GETQUI. The resultant-length argument is the address of a signed word integer into which LIB$GETQUI writes the number of characters. 3 LIB$GETSYI The Get Systemwide Information routine provides a simplified interface to the $GETSYI system service. The $GETSYI system service obtains status and identification information about the system. LIB$GETSYI returns only one item of information in a single call. Format LIB$GETSYI item-code [,resultant-value] [,resultant-string] [,resultant-length] [,cluster-system-id] [,node-name] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments item-code OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Item code specifying the desired item of information. The item- code argument is the address of a signed longword containing this item code. All valid $GETSYI item codes are accepted. resultant-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Numeric value returned by LIB$GETSYI. The resultant-value argument is the address of a longword or quadword containing this value. If an item is listed as returning only a string value, this argument is ignored. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Information returned by LIB$GETSYI. The resultant-string argument is the address of a descriptor pointing to the character string that will receive this information. If resultant-string is not specified and if the returned value has only a string representation, the error status LIB$_INVARG is returned. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of significant characters written to resultant-string, not including blank padding or truncated characters. The resultant- length argument is the address of an unsigned word into which LIB$GETSYI returns this number. cluster-system-id OpenVMS usage:identifier type: longword (unsigned) access: modify mechanism: by reference Cluster system identification (CSID) of the node for which information is to be returned. The cluster-system-id argument is the address of this CSID. If cluster-system-id is specified and is nonzero, node-name is not used. If cluster-system-id is specified as zero, LIB$GETSYI uses node-name and writes into the cluster-system-id argument the CSID corresponding to the node identified by node-name. The cluster-system-id of an OpenVMS node is assigned by the cluster-connection software and may be obtained by the DCL command SHOW CLUSTER. The value of the cluster-system-id for an OpenVMS node is not permanent; a new value is assigned to an OpenVMS node whenever it joins or rejoins the OpenVMS Cluster. If cluster-system-id is specified as -1, LIB$GETSYI assumes a wildcard operation and returns the requested information for each OpenVMS node in the cluster, one node per call. If cluster-system-id is not specified, node-name is used. node-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the node for which information is to be returned. The node-name argument is the address of a descriptor pointing to the node name string. If cluster-system-id is not specified or is specified as zero, node-name is used. If neither node-name nor cluster-system-id is specified, the caller's node is used. See the cluster-system-id argument for more information. The node name string must contain from 1 to 15 characters and must correspond exactly to the OpenVMS node name; no trailing blanks nor abbreviations are permitted. 3 LIB$GET_ACCNAM The Get Access Name Table for Protected Object Class (by Name) routine is a simplified interface to the $GET_SECURITY system service, and returns a pointer to the access name table for a protected object class that is specified by name. Format LIB$GET_ACCNAM [clsnam] , [objnam] ,accnam 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments clsnam OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor The address of a character-string descriptor pointing to the name of a protected object class. This argument is optional and defaults to FILE. objnam OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor The address of a character-string descriptor pointing to the name of a protected object. This argument is optional. If it is omitted, the access name table returned is that used for objects of the class specified by the clsnam argument. accnam OpenVMS usage:access_names type: longword (unsigned) access: write only mechanism: by reference The address of a longword into which this routine writes the address of the access name table. 3 LIB$GET_ACCNAM_BY_CONTEXT The Get Access Name Table for Protected Object Class (by Context) routine is a simplified interface to the $GET_SECURITY system service, and returns a pointer to the access name table for a protected object class that is specified by a context longword returned from $GET_SECURITY or $SET_SECURITY. Format LIB$GET_ACCNAM_BY_CONTEXT contxt ,accnam 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments contxt OpenVMS usage:context type: longword (unsigned) access: read only mechanism: by reference The address of a nonzero longword context value returned by $GET_ SECURITY or $SET_SECURITY. accnam OpenVMS usage:access_names type: longword (unsigned) access: write only mechanism: by reference The address of a longword into which this routine writes the address of the access name table. 3 LIB$GET_COMMAND The Get Line from SYS$COMMAND routine gets one record of ASCII text from the current controlling input device, specified by the logical name SYS$COMMAND. Format LIB$GET_COMMAND resultant-string [,prompt-string] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String that LIB$GET_COMMAND gets from SYS$COMMAND. The resultant- string argument is the address of a descriptor pointing to this string. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Prompt message that LIB$GET_COMMAND displays on the controlling terminal. The prompt-string argument is the address of a descriptor pointing to the prompt. Any string can be a valid prompt. By convention however, a prompt string consists of text followed by a colon (:), a space, and no carriage-return/line- feed combination. The maximum size of the prompt message is 255 characters. If the controlling input device is not a terminal, this argument is ignored. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of bytes written into resultant-string by LIB$GET_ COMMAND, not counting padding in the case of a fixed string. The resultant-length argument is the address of an unsigned word containing this length. If the input string is truncated to the size specified in the resultant-string descriptor, resultant- length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of resultant-string. 3 LIB$GET_COMMON The Get String from Common routine copies a string in the common area to the destination string. (The common area is an area of storage that remains defined across multiple image activations in a process.) The string length is taken from the first longword of the common area. Format LIB$GET_COMMON resultant-string [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which LIB$GET_COMMON writes the string copied from the common area. The resultant-string argument is the address of a descriptor pointing to the destination string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of characters written into resultant-string by LIB$GET_ COMMON, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word integer containing the number of characters copied. If the input string is truncated to the size specified in the resultant-string descriptor, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of resultant-string. 3 LIB$GET_CURR_INVO_CONTEXT (Alpha and I64 only.) The Get Current Invocation Context routine gets the current invocation context of any active procedure. A thread can obtain the invocation context of a current procedure using the following function format: Format LIB$GET_CURR_INVO_CONTEXT invo_context 4 Returns None. 4 Argument invo_context OpenVMS usage:invo_context_blk type: structure access: write only mechanism: by reference Address of an invocation context block into which the procedure context of the caller will be written. 3 LIB$GET_DATE_FORMAT The Get the User's Date Input Format routine returns information about the user's choice of a date/time input format. Format LIB$GET_DATE_FORMAT format-string [,user-context] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments format-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the translation of LIB$DT_INPUT_FORMAT. The format- string argument is the address of a descriptor pointing to this format string. user-context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context variable that retains the translation context over multiple calls to this routine. The user-context argument is the address of an unsigned longword that contains this context. The initial value of the context variable must be zero. Thereafter, the user program must not write to the cell. The user-context argument is optional. However, if a context cell is not passed, LIB$GET_DATE_FORMAT 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, HP recommends that users specify a different context cell for each calling thread. 3 LIB$GET_EF The Get Event Flag routine allocates one local event flag from a processwide pool and returns the number of the allocated flag to the caller. If no flags are available, LIB$GET_EF returns an error as its function value. Format LIB$GET_EF event-flag-number 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument event-flag-number OpenVMS usage:ef_number type: longword (unsigned) access: write only mechanism: by reference Number of the local event flag that LIB$GET_EF allocated, or - 1 if no local event flag was available. The event-flag-number argument is the address of a signed longword integer into which LIB$GET_EF writes the number of the local event flag that it allocates. 3 LIB$GET_FOREIGN The Get Foreign Command Line routine requests the calling image's command language interpreter (CLI) to return the contents of the "foreign command" line that activated the current image. Format LIB$GET_FOREIGN resultant-string [,prompt-string] [,resultant-length] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String that LIB$GET_FOREIGN uses to receive the foreign command line. The resultant-string argument is the address of a descriptor pointing to this string. If the foreign command text returned was obtained by a prompt to SYS$INPUT (see the description of flags), the text is translated to uppercase so as to be more consistent with text returned from the CLI. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional user-supplied prompt for text that LIB$GET_FOREIGN uses if no command-line text is available. The prompt-string argument is the address of a descriptor pointing to the user prompt. If omitted, no prompting is performed. It is recommended that prompt-string be specified. If prompt-string is omitted and if no command-line text is available, a zero-length string will be returned. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of bytes written into resultant-string by LIB$GET_FOREIGN, not counting padding in the case of a fixed-length resultant- string. The resultant-length argument is the address of an unsigned word into which LIB$GET_FOREIGN writes the number of bytes. flags OpenVMS usage:mask_longword type: longword (unsigned) access: modify mechanism: by reference Value that LIB$GET_FOREIGN uses to control whether or not prompting is to be performed. The flags argument is the address of an unsigned longword integer containing this value. If the low bit of flags is zero, or if flags is omitted, prompting is done only if the CLI does not return a command line. If the low bit is 1, prompting is done unconditionally. If specified, flags is set to 1 before returning to the caller. The primary use of flags is to allow a utility program to be invoked once with subcommand text on the command line, and then to repeatedly prompt for further subcommands from SYS$INPUT. This is accomplished by calling LIB$GET_FOREIGN repeatedly, specifying in the call a prompt-string string and a flags variable that is initialized to zero at the beginning of the program. The first call gets the subcommand text from the command line, after which flags will be set to 1, causing further subcommands to be requested through prompts to SYS$INPUT. 3 LIB$GET_FULLNAME_OFFSET The Get the Offset to the Starting Position of the Most Significant Part of a Full Name routine returns the offset to the starting position of the most significant part of a full name. The most significant part of a full name is determined by the underlying network services. Format LIB$GET_FULLNAME_OFFSET fullname, offset 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fullname OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Full name. The fullname argument contains the address of the descriptor pointing to this full name string. The error LIB$_INVARG is returned if fullname contains an invalid full name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if fullname is an invalid descriptor. offset OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference The offset in bytes of the starting position of the most significant part of fullname. The offset argument is the address of an unsigned word that contains this offset. The offset argument contains an unusable result when LIB$GET_ FULLNAME_OFFSET returns in error. 3 LIB$GET_HOSTNAME The Get Host Node Name routine returns the host node name of the local system. Format LIB$GET_HOSTNAME hostname [,resultant-length] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments hostname OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor The host node name. The hostname argument contains the address of a descriptor pointing to the host node name. LIB$GET_HOSTNAME writes the host node-name string into the buffer pointed to by the hostname descriptor. The error LIB$_INVSTRDES is returned if hostname is an invalid descriptor. The length field of the hostname descriptor is not updated unless hostname is a dynamic descriptor with a length less than the host node name to be returned. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage. The hostname argument contains an unusable result when LIB$GET_ HOSTNAME returns in error. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the host 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$GET_HOSTNAME returns in error. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value The value LIB$GET_HOSTNAME uses to control the form of the host node name that it returns in the output descriptor hostname. If flags is equal to 0, or if flags is omitted, the host node name returned is in the network usable form. If flags is equal to 1, the host node name returned is in the parsable form. Unused bits in flags must be 0. Nonzero unused bits result in the error condition LIB$_INVARG. 3 LIB$GET_INPUT The Get Line from SYS$INPUT routine gets one record of ASCII text from the current controlling input device, specified by SYS$INPUT. Format LIB$GET_INPUT resultant-string [,prompt-string] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String that LIB$GET_INPUT gets from the input device. The resultant-string argument is the address of a descriptor pointing to the character string into which LIB$GET_INPUT writes the text received from the current input device. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Prompt message that is displayed on the controlling terminal. The prompt-string argument is the address of a descriptor containing the prompt. Any string can be a valid prompt. By convention however, a prompt consists of text followed by a colon (:), a space, and no carriage-return/line-feed combination. The maximum size of the prompt message is 255 characters. If the controlling input device is not a terminal, this argument is ignored. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of bytes written into resultant-string by LIB$GET_ INPUT, not counting padding in the case of a fixed string. The resultant-length argument is the address of an unsigned word containing this number. If the input string is truncated to the size specified in the resultant-string descriptor, resultant- length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of resultant-string. 3 LIB$GET_INVO_CONTEXT (Alpha and I64 only.) The Get Invocation Context routine gets the invocation context of any active procedure. Format LIB$GET_INVO_CONTEXT invo_handle, invo_context 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value 4 Arguments invo_handle OpenVMS usage:invo_handle type: longword (unsigned) access: read only mechanism: by value Handle for the desired invocation. Returned by LIB$GET_INVO_ HANDLE. invo_context OpenVMS usage:invo_context_blk type: structure access: write only mechanism: by reference Address of an invocation context block into which the procedure context of the frame specified by invo_handle will be written. 3 LIB$GET_INVO_HANDLE (Alpha and I64 only.) The Get Invocation Handle routine gets an invocation handle of any active procedure. A thread can obtain an invocation handle corresponding to any invocation context block by using the following function format. Format LIB$GET_INVO_HANDLE invo_context 4 Returns OpenVMS usage:invo_handle type: longword (unsigned) access: write only mechanism: by value Invocation handle of the invocation context that was passed. If the returned value is LIB$K_INVO_HANDLE_NULL, the invocation context that was passed was invalid. 4 Argument invo_context OpenVMS usage:invo_context_blk type: structure access: read only mechanism: by reference Address of an invocation context block. Here, only the frame pointer and stack pointer fields of an invocation context block must be defined. 3 LIB$GET_LOGICAL The Get Logical Name routine calls the system service routine $TRNLNM to return information about a logical name. Format LIB$GET_LOGICAL logical-name [,resultant-string] [,resultant-length] [,table-name] [,max-index] [,index] [,acmode] [,flags] 4 Returns OpenVMS usage:cond_value type: longword access: write only mechanism: by value 4 Arguments logical-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Logical name for which LIB$GET_LOGICAL searches. The logical-name argument is the address of a descriptor pointing to the logical name string. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Logical name equivalent returned. The resultant-string argument is the address of a descriptor pointing to a character string into which LIB$GET_LOGICAL writes the equivalence name of the logical. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the equivalence name string returned by LIB$GET_ LOGICAL. The resultant-length argument is the address of an unsigned word integer into which LIB$GET_LOGICAL writes the length. table-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the table in which to search for the logical name. The table-name argument contains the address of a descriptor pointing to a character string which contains the table name. If no table is specified, LNM$FILE_DEV is used. max-index OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Largest equivalence name index. Each equivalence name for the logical name has an index associated with it. The max-index argument is the address of a signed longword integer into which LIB$GET_LOGICAL write the value. If no equivalence names (and, therefore, no index values) exist, LIB$GET_LOGICAL returns a value of -1. index OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Equivalence name index value. LIB$GET_LOGICAL will return the equivalence name string that has the specified index value. The index argument is the address of an unsigned longword integer specifying the index value. acmode OpenVMS usage:access_mode type: byte (unsigned) access: read only mechanism: by reference Access mode to be used in the translation. The acmode argument is the address of a byte specifying the access mode. The $PSLDEF macro defines symbolic names for the four access modes. When you specify the acmode argument, all names at access modes which are less privileged than the specified access mode are ignored. If you do not specify acmode, the translation is performed without regard to access mode; however, the translation process proceeds from the outermost to the innermost access modes. Thus, if two logical names with the same name, but at different access modes, exist in the same table, the name with the outermost access mode is translated. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Flags controlling the search for the logical name. The flags argument is the address of a longword integer that contains the control flags. The $LNMDEF macro defines these flags. Currently only bit 0 of this argument is used. Bit Value Description 0 LNM$M_CASE_ If set, LIB$GET_LOGICAL does not distinguish BLIND between uppercase and lowercase letters in the logical name to be translated. This is an optional argument. If omitted the default is 0. 4 Description LIB$GET_LOGICAL provides a simplified interface to the $TRNLNM system service. It provides most of the features found in $TRNLNM with some additional benefits. For string arguments, all string classes supported by the Run-Time Library are understood. The list of item descriptors, which may be difficult to construct in high-level languages, is handled internally by LIB$GET_LOGICAL. See the description of the $TRNLNM system service in the HP OpenVMS System Services Reference Manual for more information. 4 Condition_Values_Returned SS$_NORMAL Routine successfully completed. SS$_ACCVIO Access violation. Cannot access the location specified. SS$_BADPARAM Bad parameter value. SS$_IVLOGNAM Invalid logical name. The logical name or its value contained more than 255 characters. SS$_IVLOGTAB Invalid logical name table. SS$_NOLOGNAM The logical name was not found in the specified table. SS$_NOPRIV No privileges for attempted operation. SS$_TOOMANYNAM Logical name translation exceeded allowed depth. LIB$_INVARG Required argument is missing. LIB$_INSVIRMEM Insufficient virtual memory. LIB$_INVSTRDES Invalid string descriptor. LIB$_STRTRU Success, but source string truncated. LIB$_WRONUMARG Wrong number of arguments. 3 LIB$GET_LUN The Get Logical Unit Number routine allocates one logical unit number from a processwide pool. If a unit is available, its number is returned to the caller. Otherwise, an error is returned as the function value. Format LIB$GET_LUN logical-unit-number 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument logical-unit-number OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Allocated logical unit number or -1 if none was available. The logical-unit-number argument is the address of a longword into which LIB$GET_LUN returns the value of the allocated logical unit. LIB$GET_LUN can allocate logical unit numbers 100 through 119 on VAX, and 100 through 299 on Alpha and I64. 3 LIB$GET_MAXIMUM_DATE_LENGTH Given an output format and language, the Retrieve the Maximum Length of a Date/Time String routine determines the maximum possible length for the date-string string returned by LIB$FORMAT_DATE_TIME. Format LIB$GET_MAXIMUM_DATE_LENGTH date-length [,user-context] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments date-length OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the maximum possible length of the date-string argument returned to LIB$FORMAT_DATE_TIME. The date-length argument is the address of a signed longword that receives this maximum length. The length written to date-length reflects the greatest possible length of an output date/time string for the currently selected output format and natural language. For example, if the selected output date/time format includes the alphabetic, unabbreviated month name (assuming English as the natural language), the longest month name (September) would have to be taken into consideration when determining the maximum possible length of date-string. user-context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context variable that retains the translation context over multiple calls to this routine. The user-context argument is the address of an unsigned longword that contains this context. The initial value of the context variable must be zero. Thereafter, the user program must not write to the cell. The user-context parameter is optional. However, if a context cell is not passed, the routine LIB$GET_MAXIMUM_DATE_LENGTH 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, HP recommends that users specify a different context cell for each calling thread. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that allows the user to specify whether the date, time, or both are to be included in the calculation of the maximum date length. The flags argument is the address of an unsigned bit mask containing the specified values. Valid values are LIB$M_DATE_ FIELDS and LIB$M_TIME_FIELDS. The values specified for flags must correspond to the flags argument passed to LIB$FORMAT_DATE_TIME. 3 LIB$GET_PREV_INVO_CONTEXT (Alpha and I64 only.) The Get Previous Invocation Context routine gets the previous invocation context of any active procedure. A thread can obtain the invocation context of the procedure context preceding any other procedure context using the following function format. Format LIB$GET_PREV_INVO_CONTEXT invo_context 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value 4 Argument invo_context OpenVMS usage:invo_context_blk type: structure access: modify mechanism: by reference Address of an invocation context block. The given context block is updated to represent the context of the previous (calling) frame. For the purposes of this function, the minimum fields of an invocation block that must be defined are those IREG and FREG fields corresponding to registers used by a context whether the registers are preserved or not. Note that the invocation context blocks written by the routines specified in these sections define all possible fields in a context block. Such context blocks satisfy this minimum requirement. 3 LIB$GET_PREV_INVO_HANDLE (Alpha and I64 only.) The Get Previous Invocation Handle routine gets the previous invocation handle of any active procedure. A thread can obtain an invocation handle of the procedure context preceding that of a specified procedure context by using the following function format. Format LIB$GET_PREV_INVO_HANDLE invo_handle 4 Returns OpenVMS usage:invo_handle type: longword (unsigned) access: write only mechanism: by value An invocation handle for the invocation context that is previous to that which was specified as the target. 4 Argument invo_handle OpenVMS usage:invo_handle type: longword (unsigned) access: read only mechanism: by value An invocation handle that represents a target invocation context. 3 LIB$GET_SYMBOL The Get Value of CLI Symbol routine requests the calling process's command language interpreter (CLI) to return the value of a CLI symbol as a string. LIB$GET_SYMBOL then returns the string to the caller. Optionally, LIB$GET_SYMBOL can return the length of the returned value and the table in which the symbol was found. Format LIB$GET_SYMBOL symbol ,resultant-string [,resultant-length] [,table-type-indicator] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments symbol OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the symbol for which LIB$GET_SYMBOL searches. The symbol argument is the address of a descriptor pointing to the name of the symbol. LIB$GET_SYMBOL converts the symbol name to uppercase and removes trailing blanks before the search. The symbol argument must begin with a letter, a digit, a dollar sign ($), a hyphen (-), or an underscore (_). The maximum length of symbol is 255 characters. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Value of the returned symbol. The resultant-string argument is the address of a descriptor pointing to a character string into which LIB$GET_SYMBOL writes the value of the symbol. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the symbol value returned by LIB$GET_SYMBOL. The resultant-length argument is the address of an unsigned word integer into which LIB$GET_SYMBOL writes the length. table-type-indicator OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by reference Indicator of which table contained the symbol. The table-type- indicator argument is the address of a signed longword integer into which LIB$GET_SYMBOL writes the table indicator. Possible values of the table indicator are listed below. Symbolic Name Value Table LIB$K_CLI_LOCAL_ 1 Local symbol table SYM LIB$K_CLI_GLOBAL_ 2 Global symbol table SYM LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined in symbol libraries supplied by HP (macro or module name $LIBCLIDEF) and as global symbols. 3 LIB$GET_UIB_INFO Returns information from the unwind information block (UIB). Format LIB$GET_UIB_INFO uib_va [,gp_value] [,uw_desc_va] [,uw_desc_len] [,handler_fv] [,ossd_va] [,lsda_va] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments uib_va OpenVMS usage: address type: quadword (unsigned) access: read only mechanism: by reference Address of a quadword that contains the virtual address of an unwind information block (UIB). gp_value OpenVMS usage: address type: quadword (unsigned) access: read only mechanism: by reference Address of a quadword that contains the GP value that must be added to the UIB condition handler value. Must be specified if handler_fv is specified. uw_desc_va OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference Address of a quadword to store the virtual address of the unwind descriptor area. If none is present, then zero is returned. This is an optional argument. un_desc_len OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference Address of a quadword to store the length (in bytes) of the unwind descriptor area. If none are present, then zero is returned. This is an optional argument. handler_fv OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference Address of a quadword to store the function value of the condition handler. If none is present, then zero is returned. This is an optional argument. ossd_va OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference Address of a quadword to store the address of the operating system-specific data area. If none is present, then zero is returned. This is an optional argument. lsda_va OpenVMS usage: address type: quadword (unsigned) access: write mechanism: by reference Address of a quadword to store the address of the language- specific data area (LSDA). If none is present, then zero is returned. This is an optional argument. 4 Description Takes in the address of an uwind information block (UIB) and the GP value for a routine and returns the addresses of the start of the unwind descriptors (if any), the handler function descriptor (if any), and the operating system-specific data area (if any). The size in bytes of the unwind descriptors is also returned. Related Services SYS$SET_UNWIND_TABLE, SYS$CLEAR_UNWIND_TABLE, SYS$GET_UNWIND_ ENTRY_INFO, 4 Condition_Values_Returned SS$_NORMAL Routine completed successfully. LIB$_INVARG Bad UIB virtual address. 3 LIB$GET_USERS_LANGUAGE The Return the User's Language routine determines the user's choice of a natural language. The choice is determined by translating the logical SYS$LANGUAGE. Format LIB$GET_USERS_LANGUAGE language 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument language OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the translation of SYS$LANGUAGE. The language argument is the address of a descriptor pointing to this language name. 3 LIB$GET_VM The Allocate Virtual Memory routine allocates a specified number of contiguous bytes in the program region and returns the 32-bit virtual address of the first byte allocated. Format LIB$GET_VM number-of-bytes, base-address [,zone-id] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-bytes OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Number of contiguous bytes that LIB$GET_VM allocates. The number- of-bytes argument is the address of a longword integer containing the number of bytes. LIB$GET_VM allocates enough memory to satisfy the request. Your program should not reference an address before the first byte address allocated (base-address) or beyond the last byte allocated (base-address + number-of-bytes-1) since that space may be assigned to another routine. The value of number-of-bytes must be greater than zero. base-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference First virtual address of the contiguous block of bytes allocated by LIB$GET_VM. The base-address argument is the address of an unsigned longword containing this base address. zone-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference The zone-id argument is the address of a longword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE. This argument is optional. If zone-id is omitted or if the longword contains the value 0, the 32-bit default zone is used. 3 LIB$GET_VM_64 (Alpha and I64 only.) The Allocate Virtual Memory routine allocates a specified number of contiguous bytes in the program region and returns the 64-bit virtual address of the first byte allocated. Format LIB$GET_VM_64 number-of-bytes, base-address [,zone-id] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-bytes OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Number of contiguous bytes that LIB$GET_VM_64 allocates. The number-of-bytes argument is the address of a quadword integer containing the number of bytes. LIB$GET_VM_64 allocates enough memory to satisfy the request. Your program should not reference an address before the first byte address allocated (base-address) or beyond the last byte allocated (base-address + number-of-bytes minus 1) since that space may be assigned to another routine. The value of number-of-bytes must be greater than zero. base-address OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference First virtual address of the contiguous block of bytes allocated by LIB$GET_VM_64. The base-address argument is the address of an unsigned quadword containing this base address. zone-id OpenVMS usage:identifier type: quadword (unsigned) access: read only mechanism: by reference The zone-id argument is the address of a quadword that contains a zone identifier created by a previous call to LIB$CREATE_VM_ZONE_ 64 or LIB$CREATE_USER_VM_ZONE_64. This argument is optional. If zone-id is omitted or if the quadword contains the value 0, the 64-bit default zone is used. 3 LIB$GET_VM_PAGE The Get Virtual Memory Page routine allocates a specified number of contiguous pages on VAX systems or pagelets on Alpha and I64 systems of memory in the program region and returns the virtual address of the first allocated page on VAX or pagelet on Alpha or I64. Format LIB$GET_VM_PAGE number-of-pages ,base-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-pages OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Number of pages on VAX systems or pagelets on Alpha and I64 systems. The number-of-pages argument is the address of a longword integer that specifies the number of contiguous pages on VAX systems or pagelets on Alpha and I64 systems to be allocated. The value of number-of-pages must be greater than 0. base-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Block address. The base-address argument is the address of a longword that is set to the address of the first byte of the newly allocated block of pages on VAX systems or pagelets on Alpha and I64 systems. 3 LIB$GET_VM_PAGE_64 (Alpha and I64 only.) The Get Virtual Memory Page routine allocates a specified number of contiguous Alpha or I64 pagelets of memory in the program region and returns the virtual address of the first allocated pagelet. Format LIB$GET_VM_PAGE_64 number-of-pages ,base-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-pages OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Number of Alpha or I64 pagelets. The number-of-pages argument is the address of a quadword integer that specifies the number of contiguous Alpha or I64 pagelets to be allocated. The value of number-of-pages must be greater than 0. base-address OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference Block address. The base-address argument is the address of a quadword that is set to the address of the first byte of the newly allocated block of Alpha or I64 pagelets. 3 LIB$I64_GET_CURR_INVO_CONTEXT (I64 only.) The Get Current Invocation Context routine gets the invocation context of a current procedure. Format LIB$I64_GET_CURR_INVO_CONTEXT invo_context 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument invo_context OpenVMS usage:invo_context_blk type: structure access: modify only mechanism: by reference Address of an invocation context block into which the procedure context of the caller will be written. 3 LIB$I64_GET_CURR_INVO_HANDLE (I64 only.) The Get Current Invocation Handle routine gets the invocation handle for the current procedure. Format LIB$I64_GET_CURR_INVO_HANDLE invo_handle 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument invo_handle OpenVMS usage:invo_handle type: quadword access: write only mechanism: by reference Address of a quadword into which the invocation handle of the caller will be written. 3 LIB$I64_GET_FR (I64 only.) The Get Floating-Point Register routine copies the value of the floating-point register. Format LIB$I64_GET_FR invo_context, index, fr_copy 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument invo_context OpenVMS usage:invo_context_blk type: structure access: read mechanism: by reference Address of a valid invocation context block. index OpenVMS usage:index type: longword access: read mechanism: by value Floating point register index. fr_copy OpenVMS usage:floating-point value type: octaword access: write mechanism: by value Address of an octaword to receive the contents of the specified floating-point register. 3 LIB$I64_GET_INVO_CONTEXT (I64 only.) The Get Invocation Context routine gets the invocation context of any active procedure. Format LIB$I64_GET_INVO_CONTEXT invo_handle, invo_context 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments invo_handle OpenVMS usage:invo_handle type: quadword access: modify only mechanism: by reference Address of an invocation context block into which the procedure context of the frame specified by invo_handle will be written. invo_context OpenVMS usage:invo_context_blk type: structure access: write only mechanism: by reference Address of an invocation context block into which the procedure context of the frame specified by invo_handle will be written. 3 LIB$GET_INVO_HANDLE (I64 only.) The Get Invocation Handle routine obtains the invocation handle corresponding to any invocation context block. Format LIB$I64_GET_INVO_HANDLE invo_context, invo_handle 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments invo_context OpenVMS usage:invo_context_blk type: structure access: read only mechanism: by reference Address of a valid invocation context block. invo_handle OpenVMS usage:invo_handle type: quadword (unsigned) access: write only mechanism: by reference Address of the location into which the invocation context handle is to be written. If the call fails, the value of the invocation context handle is LIB$K_INVO_HANDLE_NULL. 3 LIB$I64_GET_PREV_INVO_CONTEXT (I64 only.) The Get Current Invocation Context routine obtains the invocation context of the procedure context preceding any other procedure context. Format LIB$I64_GET_PREV_INVO_CONTEXT invo_context 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument invo_context OpenVMS usage:invo_context_blk type: structure access: modify only mechanism: by reference Address of a valid invocation context block. The given invocation context block is updated to represent the context of the previous (calling) frame. The LIBICB$V_BOTTOM_OF_STACK flag of the invocation context block is set if the target frame represents the end of the invocation call chain or if stack corruption is detected. 3 LIB$I64_GET_PREV_INVO_HANDLE (I64 only.) The Get Previous Invocation Handle routine gets an invocation handle of the procedure context preceding that of a specified procedure context. Format LIB$I64_GET_PREV_INVO_HANDLE invo_handle_in, invo_handle_out 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument invo_handle_in OpenVMS usage:invo_handle type: quadword access: read only mechanism: by reference The address of an invocation handle that represents a target invocation context. invo_handle_out OpenVMS usage:invo_handle type: quadword access: write only mechanism: by reference Address of the location into which the invocation context handle of the previous context is to be written. If the call fails, the value of the previous invocation context handle is LIB$K_INVO_ HANDLE_NULL. 3 LIB$I64_GET_UNWIND_HANDLER_FV (I64 only.) The Get Function Value For Condition Handler routine finds the function value (address of the procedure descriptor) for the condition handler. Format LIB$I64_GET_UNWIND_HANDLER_FV pc_value, handler_fv 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pc_value OpenVMS usage:PC value type: quadword access: read mechanism: by reference Address of a location that contains the PC value. pc_value is used to find the unwind information block and the unwind information block condition handler pointer. handler_fv OpenVMS usage:address type: quadword access: write mechanism: by reference A quadword to receive the function value of the procedure descriptor for the condition handler, if there is one. 3 LIB$I64_GET_UNWIND_LSDA (I64 only.) The Find Address of Unwind Information Block Language-Specific Data routine finds the address of the unwind information block language-specific data area. Format LIB$I64_GET_UNWIND_LSDA pc_value, unwind_lsda_p 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pc_value OpenVMS usage:PC value type: quadword access: read mechanism: by reference Address of a quadword to receive the address of the language- specific data area, if there is one. unwind_lsda_p OpenVMS usage:address type: quadword access: write mechanism: by reference Address of a location that contains the PC value. pc_value is used to find the unwind information block and the unwind information block language-specific data area address. 3 LIB$I64_GET_UNWIND_OSSD (I64 only.) The Find Address of the Unwind Information Block Operating System-Specific Data Area routine finds the address of the unwind information block operating system-specific data area. Format LIB$I64_GET_UNWIND_OSSD pc_value, unwind_ossd_p 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pc_value OpenVMS usage:PC value type: quadword access: read mechanism: by reference Address of a location that contains the PC value. pc_value is used to find the unwind information block and the unwind information block operating system-specific data area address. unwind_ossd_p OpenVMS usage:address type: quadword access: write mechanism: by reference Address of a quadword to receive the address of the operating system-specific data area. 3 LIB$I64_IS_AST_DISPATCH_FRAME (I64 only.) The Determine AST Exception Frame Dispatch routine determines whether a given PC value represents an AST dispatch frame. Format LIB$I64_IS_AST_DISPATCH_FRAME pc_value 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pc_value OpenVMS usage:PC value type: quadword access: read mechanism: by reference Address of a quadword that contains the PC value. The pc_value is used to find the operating system-specific data area in the unwind information for this routine. 3 LIB$I64_IS_EXC_DISPATCH_FRAME (I64 only.) The Determine Exception Frame Dispatch routine determines whether a given PC value represents an exception dispatch frame. Format LIB$I64_IS_EXC_DISPATCH_FRAME pc_value 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pc_value OpenVMS usage:PC value type: quadword access: read mechanism: by reference Address of a quadword that contains the PC value. The pc_value is used to find the operating system-specific data area in the unwind information for this routine. 3 LIB$I64_PREV_INVO_END (I64 only.) The End Call Tracing Operations routine should be called at the conclusion of call tracing operations to free the memory used to process unwind descriptors. Format LIB$I64_PREV_INVO_END (invo_context) 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument invo_context OpenVMS usage:invo_context_blk type: structure access: modify only mechanism: by reference Address of a valid invocation context block previously used for call tracing. 3 LIB$I64_PUT_INVO_REGISTERS (I64 only.) The Put Invocation Registers routine updates the fields of a given procedure invocation context. Note that if user override routines are specified in the invocation context block, then they are used to find and modify the invocation context. Format LIB$I64_PUT_INVO_REGISTERS invo_handle, invo_context, [,gr_mask] [,fr_mask] [,br_mask] [,pr_mask] [,misc_mask] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments invo_handle OpenVMS usage:invo_handle type: quadword (unsigned) access: read only mechanism: by reference Handle for the invocation to be updated. invo_context OpenVMS usage:invo_context_blk type: structure access: read only mechanism: by reference Address of a valid invocation context block that contains new register contents. Each register that is set in the xx_mask argument (along with its NaT bit, if any) is updated using the value found in the corresponding IREG[n], FREG[n], BRANCH[n], or PRED[n] field. GP, TP, and AI can also be updated in this way. No other fields of the invocation context block are used. gr_mask OpenVMS usage:mask_octaword type: 128-bit vector access: read only mechanism: by reference Address of a 128-bit bit vector, where each bit corresponds to a register field in the invo_context argument. Bits 0 through 127 correspond to IREG[0] through IREG[127]. Bit 0 corresponds to R0, which cannot be written, and is ignored. Bit 1 corresponds to the global data pointer (GP). Bit 13 corresponds to the thread pointer (TP). Bit 25 corresponds to the argument information register (AI). If bit 12, which corresponds to SP, is set, then no changes are made. fr_mask OpenVMS usage:mask_octaword type: 128-bit vector access: read only mechanism: by reference Address of a 128-bit bit vector, where each bit corresponds to a register field in the passed invo_context. To update floating-point registers F32-F127, provide a pointer to an array of 96 octawords in LIBICB$PH_F32_F127. Bits 0 through 127 correspond to FREG[0] through FREG[127]. Bit 0 corresponds to F0, which cannot be written, and is ignored. Bit 1 corresponds to F1, which cannot be written, and is ignored. br_mask OpenVMS usage:mask_byte type: 8-bit vector access: read only mechanism: by reference Address of a 8-bit bit vector, where each bit corresponds to a register field in the passed invo_context. Bits 0 through 7 correspond to BRANCH[0] through BRANCH[7]. pr_mask OpenVMS usage:mask_quadword type: 64-bit vector access: read only mechanism: by reference Address of a 64-bit bit vector, where each bit corresponds to a register field in the passed invo_context. Bits 0 through 63 correspond to PRED[0] through PRED[63]. misc_mask OpenVMS usage:mask_quadword type: 64-bit vector access: read only mechanism: by reference Address of a 64-bit bit vector, where each bit corresponds to a register field in the passed invo_context as follows: Bit 0=PC. Bit 1=FPSR. Bits 2-63 are reserved. 3 LIB$I64_SET_FR (I64 only.) The Set Floating-Point Register routine writes the invocation context block floating-point registry entry corresponding to a floating-point register value. Format LIB$I64_SET_FR invo_context, index, fr_copy 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments invo_context OpenVMS usage:invo_context_blk type: structure access: modify mechanism: by reference Address of a valid invocation context block. index OpenVMS usage:index type: longword access: read mechanism: by value Index into the FREG array of the invocation context block. fr_copy OpenVMS usage:floating-point value type: octaword access: write mechanism: by value Address of an octaword that contains the floating-point value to be written to the invocation context block. 3 LIB$I64_SET_GR (I64 only.) The Copy Invocation Block General Register routine writes the invocation context block general register. Format LIB$I64_SET_GR invo_context, index, fr_copy 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments invo_context OpenVMS usage:invo_context_blk type: structure access: modify mechanism: by reference Address of a valid invocation context block. index OpenVMS usage:index type: longword access: read mechanism: by value Index into the IREG array of the invocation context block. gr_copy OpenVMS usage:integer value type: quadword access: write mechanism: by value Address of a quadword that contains the value to be written to the invocation context block. 3 LIB$I64_SET_PC (I64 only.) The Write Context Block and Quadword PC Value routine writes invocation context block PC. Format LIB$I64_SET_PC invo_context, pc_copy 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments invo_context OpenVMS usage:invo_context_blk type: structure access: modify mechanism: by reference Address of a valid invocation context block. pc_copy OpenVMS usage:PC value type: quadword access: read mechanism: by reference Address of a quadword that contains the PC value to be written to the invocation context block. 3 LIB$ICHAR The Convert First Character of String to Integer routine converts the first character of a source string to an 8-bit ASCII integer extended to a longword. Format LIB$ICHAR source-string 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value First character of the source string. This character is returned by LIB$ICHAR as an 8-bit ASCII value extended to a longword. If the source string has zero length, LIB$ICHAR returns a zero. 4 Argument source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string whose first character is converted to an integer by LIB$ICHAR. The source-string argument is the address of a descriptor pointing to this source string. 3 LIB$INDEX The Index to Relative Position of Substring routine returns an index, which is the relative position of the first occurrence of a substring in the source string. Format LIB$INDEX source-string ,sub-string 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The relative position of the first character of the substring if found, or zero if not found. On Alpha and I64 systems, if the relative position of the substring can exceed 2**32-1, assign the return value to a quadword to ensure that you retrieve the correct relative position. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string to be searched by LIB$INDEX. The source-string argument is the address of a descriptor pointing to this source string. sub-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Substring to be found. The sub-string argument is the address of a descriptor pointing to this substring. 3 LIB$INIT_DATE_TIME_CONTEXT The Initialize the Context Area Used in Formatting Dates and Times for Input or Output routine allows the user to initialize the context area used by LIB$FORMAT_DATE_TIME or LIB$CONVERT_ DATE_STRING with specific strings, instead of through logical name translation. Format LIB$INIT_DATE_TIME_CONTEXT user-context ,component ,init-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments user-context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference User context that retains the translation context over multiple calls to this routine. The user-context argument is the address of an unsigned longword that contains this context. The initial value of the context variable must be zero. Thereafter, the user program must not write to the cell. component OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference The component of the context that is being initialized. The component argument is the address of a signed longword that indicates this component. Only one component can be initialized per call to LIB$INIT_DATE_TIME; these component codes are shown in the following list. o LIB$K_MONTH_NAME o LIB$K_MONTH_NAME_ABB o LIB$K_FORMAT_MNEMONICS o LIB$K_WEEKDAY_NAME o LIB$K_WEEKDAY_NAME_ABB o LIB$K_RELATIVE_DAY_NAME o LIB$K_MERIDIEM_INDICATOR o LIB$K_OUTPUT_FORMAT o LIB$K_INPUT_FORMAT o LIB$K_LANGUAGE init-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor The characters that are to be used in formatting dates and times for input or output. The init-string argument is the address of a descriptor pointing to this string. 3 LIB$INIT_TIMER The Initialize Times and Counts routine stores the current values of specified times and counts for use by LIB$SHOW_TIMER or LIB$STAT_TIMER. Format LIB$INIT_TIMER [context] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context variable that retains the values of the times and counts. The context argument contains the address of an unsigned longword that is this context. When you call LIB$INIT_TIMER, you must use the optional context argument only if you want to maintain several sets of statistics simultaneously. o If context is omitted, the control block is allocated in static storage. This method is not AST reentrant. o If context is zero, a control block is allocated in dynamic heap storage. The times and counts will be stored in that block and the address of the block returned in context. This method is fully reentrant and modular. o If context is nonzero, it is considered to be the address of a control block previously allocated by a call to LIB$INIT_ TIMER. If so, the control block is reused, and fresh times and counts are stored in it. When LIB$INIT_TIMER returns, the block of storage referred to by context will contain the times and counts. 3 LIB$INSERT_TREE The Insert Entry in a Balanced Binary Tree routine inserts a node in a balanced binary tree. Format LIB$INSERT_TREE treehead ,symbol ,flags ,user-compare-routine ,user-allocation-procedure ,new-node [,user-data] 4 Returns OpenVMS usage:cond_value type: longword (signed) access: write only mechanism: by value 4 Arguments treehead OpenVMS usage:address type: address access: modify mechanism: by reference Tree head for the binary tree. The treehead argument is the address of a longword that is this tree head. The initial value of treehead is 0. symbol OpenVMS usage:user_arg type: longword (unsigned) access: unspecified mechanism: unspecified Key to be inserted. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Control flags. The flags argument is the address of the control flags. Currently only bit 0 is used. Bit Action if Set Action if Clear 0 Duplicate The address of the existing duplicate entry entries are is returned to the new-node argument. inserted. user-compare-routine OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied compare routine that LIB$INSERT_TREE calls to compare a symbol with a node. The user-compare-routine argument is required; LIB$INSERT_TREE calls the compare routine for every node except the first node in the tree. The value returned by the compare routine indicates the relationship between the symbol key and the node. user-allocation-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied allocate routine that LIB$INSERT_TREE calls to allocate virtual memory for a node. The user-allocation-procedure argument is required; LIB$INSERT_TREE always calls the allocate routine. new-node OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Location where the new key is inserted. The new-node argument is the address of an unsigned longword that is the address of the new node. user-data OpenVMS usage:user_arg type: unspecified access: unspecified mechanism: by value User data that LIB$INSERT_TREE passes to the compare and allocate routines. The user-data argument is optional. 3 LIB$INSERT_TREE_64 (Alpha and I64 only.) The Insert Entry in a Balanced Binary Tree routine inserts a node in a balanced binary tree. Format LIB$INSERT_TREE_64 treehead ,symbol ,flags ,user-compare-routine ,user-allocation-procedure ,new-node [,user-data] 4 Returns OpenVMS usage:cond_value type: longword (signed) access: write only mechanism: by value 4 Arguments treehead OpenVMS usage:address type: address access: modify mechanism: by reference Tree head for the binary tree. The treehead argument is the address of a quadword that is this tree head. The initial value of treehead is 0. symbol OpenVMS usage:user_arg type: quadword (unsigned) access: unspecified mechanism: unspecified Key to be inserted. flags OpenVMS usage:mask_quadword type: quadword (unsigned) access: read only mechanism: by reference Control flags. The flags argument is the address of the control flags. Currently only bit 0 is used. Bit Description 0 If clear, the address of the existing duplicate entry is returned to the new-node argument. If set, duplicate entries are inserted. user-compare-routine OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied compare routine that LIB$INSERT_TREE_64 calls to compare a symbol with a node. The user-compare-routine argument is required; LIB$INSERT_TREE_64 calls the compare routine for every node except the first node in the tree. The value returned by the compare routine indicates the relationship between the symbol key and the node. user-allocation-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied allocate routine that LIB$INSERT_TREE_64 calls to allocate virtual memory for a node. The user-allocation- procedure argument is required; LIB$INSERT_TREE_64 always calls the allocate routine. new-node OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference Location where the new key is inserted. The new-node argument is the address of an unsigned quadword that is the address of the new node. user-data OpenVMS usage:user_arg type: unspecified access: unspecified mechanism: by value User data that LIB$INSERT_TREE_64 passes to the compare and allocate routines. The user-data argument is optional. 3 LIB$INSQHI The Insert Entry at Head of Queue routine inserts a queue entry at the head of the specified self-relative longword interlocked queue. LIB$INSQHI makes the INSQHI instruction available as a callable routine. Format LIB$INSQHI entry ,header [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments entry OpenVMS usage:unspecified type: unspecified access: modify mechanism: by reference, array reference Entry to be inserted by LIB$INSQHI. The entry argument contains the address of this signed quadword-aligned array that must be at least 8 bytes long. Bytes following the first 8 bytes can be used for any purpose by the calling program. For Alpha and I64 systems, the entry argument must contain a 32- bit sign-extended address. An illegal operand exception occurs for any other form of address. header OpenVMS usage:quadword_signed type: quadword integer (signed) access: modify mechanism: by reference Queue header specifying the queue into which entry is to be inserted. The header argument contains the address of this signed aligned quadword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. For Alpha systems, the header argument must contain a 32-bit sign-extended address. An illegal operand exception occurs for any other form of address. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the insertion is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of an unsigned longword that contains the retry count value. A value of 1 causes no retries. The default value is 10. 3 LIB$INSQHIQ (Alpha and I64 only.) The Insert Entry at Head of Queue routine inserts a queue entry at the head of the specified self-relative quadword interlocked queue. LIB$INSQHIQ makes the INSQHIQ instruction available as a callable routine. Format LIB$INSQHIQ entry ,header [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments entry OpenVMS usage:unspecified type: unspecified access: modify mechanism: by reference, array reference Entry to be inserted by LIB$INSQHIQ. The entry argument contains the address of this signed octaword-aligned array that must be at least 16 bytes long. Bytes following the first 16 bytes can be used for any purpose by the calling program. header OpenVMS usage:octaword_signed type: octaword integer (signed) access: modify mechanism: by reference Queue header specifying the queue into which entry is to be inserted. The header argument contains the address of this signed aligned octaword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the insertion is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of an unsigned longword that contains the retry count value. A value of 1 causes no retries. The default value is 10. 3 LIB$INSQTI The Insert Entry at Tail of Queue routine inserts a queue entry at the tail of the specified self-relative longword interlocked queue. LIB$INSQTI makes the INSQTI instruction available as a callable routine. Format LIB$INSQTI entry ,header [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments entry OpenVMS usage:unspecified type: unspecified access: modify mechanism: by reference, array reference Entry to be inserted at the tail of the queue by LIB$INSQTI. The entry argument contains the address of this signed quadword- aligned array that must be at least 8 bytes long. Bytes following the first 8 bytes can be used for any purpose by the calling program. For Alpha and I64 systems, the entry argument must contain a 32- bit sign-extended address. An illegal operand exception occurs for any other form of address. header OpenVMS usage:quadword_signed type: quadword integer (signed) access: modify mechanism: by reference Queue header specifying the queue into which the queue entry is to be inserted. The header argument contains the address of this signed aligned quadword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. For Alpha and I64 systems, the header argument must contain a 32-bit sign-extended address. An illegal operand exception occurs for any other form of address. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the insertion is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of a longword which contains the retry count value. The default value is 10. 3 LIB$INSQTIQ (Alpha and I64 only.) The Insert Entry at Tail of Queue routine inserts a queue entry at the tail of the specified self-relative quadword interlocked queue. LIB$INSQTIQ makes the INSQTIQ instruction available as a callable routine. Format LIB$INSQTIQ entry ,header [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments entry OpenVMS usage:unspecified type: unspecified access: modify mechanism: by reference, array reference Entry to be inserted at the tail of the queue by LIB$INSQTIQ. The entry argument contains the address of this signed octaword- aligned array that must be at least 16 bytes long. Bytes following the first 16 bytes can be used for any purpose by the calling program. header OpenVMS usage:octaword_signed type: octaword integer (signed) access: modify mechanism: by reference Queue header specifying the queue into which the queue entry is to be inserted. The header argument contains the address of this signed aligned octaword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the insertion is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of a longword that contains the retry count value. The default value is 10. 3 LIB$INSV The Insert a Variable Bit Field routine replaces the variable bit field specified by the base, position, and size arguments with bits 0 through (size-1) of the source field. If the size of the bit field is zero, nothing is inserted. LIB$INSV makes the VAX INSV instruction available as a callable routine. Format LIB$INSV longword-integer-source ,position ,size ,base-address 4 Returns None. 4 Arguments longword-integer-source OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Source field to be inserted by LIB$INSV. The longword-integer- source argument is the address of a signed longword integer that contains this source field. position OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Bit position relative to the base address where insertion of longword-integer-source is to begin. The position argument is the address of a longword integer that contains this relative bit position. size OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Size of the bit field to be inserted by LIB$INSV. The size argument is the address of an unsigned byte that contains the size of this bit field. The maximum size is 32 bits. base-address OpenVMS usage:address type: address access: read only mechanism: by value Field into which LIB$INSV writes the source field. The base- address argument is an unsigned longword containing the base address of this aligned bit string. 3 LIB$INT_OVER The Integer Overflow Detection routine enables or disables integer overflow detection for the calling routine activation. The previous integer overflow enable setting is returned. This routine is available on OpenVMS Alpha and I64 systems in translated form and is applicable to translated VAX images only. Format LIB$INT_OVER new-setting 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value Old integer overflow enable setting (the previous contents of SF$W_PSW[PSW$V_IV] in the caller's frame). 4 Argument new-setting OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference New integer overflow enable setting. The new-setting argument is the address of an unsigned longword that contains the new integer overflow enable setting. Bit 0 set to 1 means enable, bit 0 set to 0 means disable. 3 LIB$LEN The Length of String Returned as Longword Value routine returns the length of a string. Format LIB$LEN source-string 4 Returns OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by value Length of the source string, extracted and zero-extended to 32 bits. 4 Argument source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string whose length is returned by LIB$LEN. The source- string argument contains the address of a descriptor pointing to this source string. 3 LIB$LOCC The Locate a Character routine locates a character in a string by comparing successive bytes in the string with the character specified. The search continues until the character is found or the string has no more characters. LIB$LOCC makes the VAX LOCC instruction available as a callable routine. Format LIB$LOCC character-string ,source-string 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The relative position from the start of source-string to the first equal character or zero if no match is found. 4 Arguments character-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String whose initial character is used by LIB$LOCC in the search. The character-string argument contains the address of a descriptor pointing to this string. Only the first character of character-string is used, and its length is not checked. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String to be searched by LIB$LOCC. The source-string argument is the address of a descriptor pointing to this character string. 3 LIB$LOCK_IMAGE Locks the specified image in the process's working set. Format LIB$LOCK_IMAGE address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument address OpenVMS usage:address type: quadword access: read only mechanism: by value Address of a byte within the image to be locked in the working set. If the address argument is 0, the current image (which contains the call to LIB$LOCK_IMAGE) is locked in the working set. 3 LIB$LOOKUP_KEY The Look Up Keyword in Table routine scans a table of keywords to find one that matches the keyword or keyword abbreviation specified by search-string. Format LIB$LOOKUP_KEY search-string ,key-table-array [,key-value] [,keyword-string] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments search-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String for which LIB$LOOKUP_KEY will search in the keyword table. The search-string argument is the address of a descriptor pointing to this string. key-table-array OpenVMS usage:unspecified type: unspecified access: read only mechanism: by reference, array reference Keyword table. The key-table-array argument contains the address of an array that is this keyword table. key-value OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Associated value of the keyword found by LIB$LOOKUP_KEY. The key- value argument contains the address of an unsigned longword into which LIB$LOOKUP_KEY writes the associated value of the matched keyword. keyword-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Full keyword string matched. The keyword-string argument contains the address of a character-string descriptor. LIB$LOOKUP_ KEY writes the complete text of the matched keyword into the character string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of characters copied into the character-string pointed to by keyword-string, not counting padding in the case of a fixed- length string. The resultant-length argument is the address of an unsigned word integer that contains the number of characters in the matched keyword that were copied into the character-string. 3 LIB$LOOKUP_TREE The Look Up an Entry in a Balanced Binary Tree routine looks up an entry in a balanced binary tree. Format LIB$LOOKUP_TREE treehead ,symbol ,user-compare-routine ,new-node 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments treehead OpenVMS usage:address type: address access: read only mechanism: by reference Tree head for the binary tree. The treehead argument is the address of an unsigned longword that is this tree head. symbol OpenVMS usage:user_arg type: longword (unsigned) access: unspecified mechanism: unspecified Key to be looked up in the binary tree. user-compare-routine OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied compare routine that LIB$LOOKUP_TREE calls to compare a symbol with a node. The value returned by the compare routine indicates the relationship between the symbol key and the current node. new-node OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Location where the new symbol was found. The new-node argument is the address of an unsigned longword that is the new node location. 3 LIB$LOOKUP_TREE_64 (Alpha and I64 only.) The Look Up an Entry in a Balanced Binary Tree routine looks up an entry in a balanced binary tree. Format LIB$LOOKUP_TREE_64 treehead ,symbol ,user-compare-routine ,new-node 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments treehead OpenVMS usage:address type: address access: read only mechanism: by reference Tree head for the binary tree. The treehead argument is the address of an unsigned quadword that is this tree head. symbol OpenVMS usage:user_arg type: quadword (unsigned) access: unspecified mechanism: unspecified Key to be looked up in the binary tree. user-compare-routine OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied compare routine that LIB$LOOKUP_TREE_64 calls to compare a symbol with a node. The value returned by the compare routine indicates the relationship between the symbol key and the current node. new-node OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference Location where the new symbol was found. The new-node argument is the address of an unsigned quadword that is the new node location. 3 LIB$LP_LINES The Lines on Each Printer Page routine computes the default number of lines on a printer page. This routine can be used by native-mode OpenVMS utilities that produce listing files and paginate files. Format LIB$LP_LINES 4 Returns OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by value The default number of lines on a physical printer page. If the logical name translation or conversion to binary fails, a default value of 66 is returned. 4 Arguments None. 3 LIB$MATCHC The Match Characters, Return Relative Position routine searches a source string for a specified substring and returns an index, which is the relative position of the first occurrence of a substring in the source string. The relative character positions returned by LIB$MATCHC are numbered 1, 2, . . . , n. Thus, zero means that the substring was not found. Format LIB$MATCHC sub-string ,source-string 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The relative position of the first character of the substring if found, or zero if not found. 4 Arguments sub-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Substring to be found. The sub-string argument is the address of a descriptor pointing to this substring. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string to be searched by LIB$MATCHC. The source-string argument is the address of a descriptor pointing to this source string. 3 LIB$MATCH_COND The Match Condition Values routine checks to see if a given condition value matches a list of condition values that you supply. Format LIB$MATCH_COND match-condition-value ,compare-condition-value ,... 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value A zero, if the input condition value did not match any condition value in the list, or i-1, for a match between the first argument and the ith argument. 4 Arguments match-condition-value OpenVMS usage:cond_value type: longword (unsigned) access: read only mechanism: by reference Condition value to be matched. The match-condition-value argument is the address of an unsigned longword that contains this condition value. compare-condition-value OpenVMS usage:cond_value type: longword (unsigned) access: read only mechanism: by reference The condition values to be compared to match-condition-value. The compare-condition-value arguments are the addresses of the unsigned longwords that contain these condition values. 3 LIB$MOVC3 The Move Characters routine makes the VAX MOVC3 instruction available as a callable routine. The source item is moved to the destination item. Overlap of the source and destination items does not affect the result. Format LIB$MOVC3 word-integer-length ,source ,destination 4 Returns None. 4 Arguments word-integer-length OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Number of bytes to be moved from source to destination by LIB$MOVC3. The word-integer-length argument is the address of an unsigned word that contains this number of bytes. The maximum transfer is 65,535 bytes. source OpenVMS usage:unspecified type: unspecified access: read only mechanism: by reference Item to be moved. The source argument is the address of this item. destination OpenVMS usage:unspecified type: unspecified access: write only mechanism: by reference Item into which source will be moved. The destination argument is the address of this item. 3 LIB$MOVC5 The Move Characters with Fill routine makes the VAX MOVC5 instruction available as a callable routine. The source item is moved to the destination item. Overlap of the source and destination items does not affect the result. Format LIB$MOVC5 word-integer-source-length ,source [,fill] ,word-integer-destination-length ,destination 4 Returns None. 4 Arguments word-integer-source-length OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Number of bytes in the source item. The word-integer-source- length argument is the address of an unsigned word that contains this number of bytes. The maximum length of source is 65,535 bytes. source OpenVMS usage:unspecified type: unspecified access: read only mechanism: by reference Item to be moved by LIB$MOVC5. The source argument is the address of this item. If word-integer-source-length is zero, indicating that destination is to be entirely filled by the fill character, then source is ignored by LIB$MOVC5. fill OpenVMS usage:byte_signed type: byte integer (signed) access: read only mechanism: by reference Character used to pad source to the length of destination. The fill argument is the address of a signed byte integer that contains this fill character. If word-integer-destination-length is less than or equal to word-integer-source-length, fill is unused and may be omitted. word-integer-destination-length OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Length of destination in bytes. The word-integer-destination- length argument is the address of an unsigned word that contains this number of bytes. The maximum value of word-integer- destination-length is 65,535 bytes. destination OpenVMS usage:unspecified type: unspecified access: write only mechanism: by reference Item into which source will be moved. The destination argument is the address of this item. 3 LIB$MOVTC The Move Translated Characters routine moves the source string, character by character, to the destination string after translating each character using the specified translation table. LIB$MOVTC makes the VAX MOVTC instruction available as a callable routine. Format LIB$MOVTC source-string ,fill-character ,translation-table ,destination-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string to be translated and moved by LIB$MOVTC. The source-string argument is the address of a descriptor pointing to this source string. fill-character OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Fill character used to pad source-string to the length of destination-string. The fill-character argument is the address of a descriptor pointing to a string. The first character of this string is used as the fill character. The length of this string is not checked and fill-character is not translated. translation-table OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Translation table used by LIB$MOVTC. The translation-table argument is the address of a descriptor pointing to the translation table string. The translation table string is assumed to be 256 characters long. You can use any one of the translation tables supplied by HP, or you can create your own. Translation tables supplied by HP have names in the format LIB$AB_xxx_yyy, which represent the addresses of the 256-byte translation tables and can be accessed as external (string) variables. If a particular language cannot generate descriptors for external strings, then you must create them manually. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which LIB$MOVTC writes the translated source-string. The destination-string argument is the address of a descriptor pointing to this destination string. 3 LIB$MOVTUC The Move Translated Until Character routine moves the source string, character by character, to the destination string after translating each character using the specified translation table until the stop character is encountered. LIB$MOVTUC makes the VAX MOVTUC instruction available as a callable routine. Format LIB$MOVTUC source-string ,stop-character ,translation-table ,destination-string [,fill-character] 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The relative position in the source string of the character that is translated to the stop character. Zero is returned if the stop character is not found. This value is set to -1 if destination- string cannot be allocated. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string to be translated and moved by LIB$MOVTUC. The source-string argument is the address of a descriptor pointing to this source string. stop-character OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Stop character that causes LIB$MOVTUC to stop translating the source string. The stop-character argument is the address of a descriptor pointing to a string. The first character of this string is used as the stop character. The length of this string is not checked. During the translation, LIB$MOVTUC accesses each character in the source string and uses it as an index into the translation table. If this translated character is the specified stop character, translation stops, and stop-character is not translated. translation-table OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Translation table used by LIB$MOVTUC. The translation-table argument is the address of a descriptor pointing to the translation table string. The translation table string is assumed to be 256 characters long. You can use any of the translation tables included in the Description section of LIB$MOVTC, or you can create your own. When using a translation table supplied by HP, the names LIB$AB_ xxx_yyy represent the addresses of the 256-byte translation tables, and can be accessed as external (string) variables. If a particular language cannot generate descriptors for external strings, then they must be created manually. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which LIB$MOVTUC writes the translated source-string. The destination-string argument is the address of a descriptor pointing to this destination string. fill-character OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Character used to pad source-string to the length of destination- string. The fill-character argument is the address of a descriptor pointing to a string. The first character of this string is used as the fill character. The length of this string is not checked and fill-character is not translated. If the fill character is included, the remainder of the destination string (after the stop character) is filled with the specified fill character. If it is not included, the remainder of the destination string remains unchanged. 3 LIB$MULTF_DELTA_TIME The Multiply Delta Time by an F-Floating Scalar routine multiplies a delta time by an F-floating scalar. Format LIB$MULTF_DELTA_TIME multiplier ,delta-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments multiplier OpenVMS usage:floating_point type: F_floating access: read only mechanism: by reference The value by which LIB$MULTF_DELTA_TIME multiplies the delta time. The multiplier argument is the address of an F-floating value containing the scalar. If multiplier is negative, the absolute value of multiplier is used. delta-time OpenVMS usage:date_time type: quadword (unsigned) access: modify mechanism: by reference The delta time to be multiplied. The delta-time argument is the address of an unsigned quadword containing the number to be multiplied. The initial delta-time argument must be greater than 0. After LIB$MULTF_DELTA_TIME performs the multiplication, the result is returned to delta-time. (The original delta-time value is overwritten.) 3 LIB$MULTS_DELTA_TIME (Alpha and I64 only) The Multiply Delta Time by an IEEE S- Floating Scalar routine multiplies a delta time by an IEEE S- floating scalar. Format LIB$MULTS_DELTA_TIME multiplier ,delta-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments multiplier OpenVMS usage:floating_point type: IEEE S_floating access: read only mechanism: by reference The value by which LIB$MULTS_DELTA_TIME multiplies the delta time. The multiplier argument is the address of an IEEE S- floating value containing the scalar. If multiplier is negative, the absolute value of multiplier is used. delta-time OpenVMS usage:date_time type: quadword (unsigned) access: modify mechanism: by reference The delta time to be multiplied. The delta-time argument is the address of an unsigned quadword containing the number to be multiplied. The initial delta-time argument must be greater than 0. After LIB$MULTS_DELTA_TIME performs the multiplication, the result is returned to delta-time. (The original delta-time value is overwritten.) 3 LIB$MULT_DELTA_TIME The Multiply Delta Time by Scalar routine multiplies a delta time by a longword integer scalar. Format LIB$MULT_DELTA_TIME multiplier ,delta-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments multiplier OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference The value by which LIB$MULT_DELTA_TIME multiplies the delta time. The multiplier argument is the address of a signed longword containing the integer scalar. If multiplier is negative, the absolute value of multiplier is used. delta-time OpenVMS usage:date_time type: quadword (unsigned) access: modify mechanism: by reference The delta time to be multiplied. The delta-time argument is the address of an unsigned quadword containing the number to be multiplied. The initial delta-time argument must be greater than 0. After LIB$MULT_DELTA_TIME performs the multiplication, the result is returned to delta-time. (The original delta-time value is overwritten.) 3 LIB$PARSE_ACCESS_CODE The Parse Access Encoded Name String routine parses and translates a string of access names into a mask for a particular ownership category. Format LIB$PARSE_ACCESS_CODE access-string, [access-names,] ownership-category, access-mask, [end-position] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments access-string OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor The address of a character-string descriptor pointing to a string of access names. Each access name is abbreviated to one letter. An example of a valid access string is RWE. Access names are specific to each of the different object classes. See the HP OpenVMS Guide to System Security for a complete list of all valid access names. access-names OpenVMS usage:access_names type: array [0..31] of quadword string descriptor access: read only mechanism: by reference The address of the access name table for the associated object class. For example, it is the value returned by the LIB$GET_ ACCNAM routine in the accnam longword. This parameter is optional and defaults to the access name table for the FILE object class. ownership-category OpenVMS usage:mask_word type: word (unsigned) access: read only mechanism: by reference The address of a word that indicates the ownership category the access names refer to: Ownership Category Mask Value System 0000000000001111 Owner 0000000011110000 Group 0000111100000000 World 1111000000000000 access-mask OpenVMS usage:mask_word type: word (unsigned) access: write only mechanism: by reference The address of a word into which this routine writes the access mask. In this mask, a set bit means the access was requested for the specified ownership. Note that this is the opposite of the standard protection format where a set bit means no access. end-position OpenVMS usage:word_signed type: word (signed) access: write only mechanism: by reference The number of characters from access-string processed by LIB$PARSE_ACCESS_CODE. In the case of an error in parsing the access string, the offset to the offending location is returned. 3 LIB$PARSE_SOGW_PROT The Parse Protection String routine parses and translates a protection string into a protection mask. Format LIB$PARSE_SOGW_PROT protection-string, [access-names], protection-mask, ownership-mask, [end-position] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments protection-string OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor The address of a character-string descriptor pointing to the protection string. The string components are: o Ownership name - System,Owner,Group,World. Ownership names can be specified in full or truncated to any number of characters. Matching is case blind, and spacing is ignored. o Access name - Access names are always abbreviated to one letter. For example, access names for files are R (for read), W (for write), E (for execute), and D (for delete). Any combination can be passed. For example, RWE is a valid combination. A null access name specification means no access. o Separators - Access names are separated from ownership names by either a colon (:) or an equal sign (=). The comma (,) is the list separator. A null access name specification means no access. An example of a valid protection string is: SYSTEM=RWED,OWNER:RWED,GROUP,WORLD:R access-names OpenVMS usage:access_names type: array [0..31] of quadword string descriptor access: read only mechanism: by reference The address of the access name table for the associated object class. For example, it is the value returned by the LIB$GET_ ACCNAM routine in the accnam longword. This parameter is optional and defaults to the access name table for the FILE object class. protection-mask OpenVMS usage:protection type: word (unsigned) access: write only mechanism: by reference The address of a word into which this routine writes a 16-bit protection mask translation of the protection string. Each bit set in the mask indicates no access for the access type it represents. ownership-mask OpenVMS usage:mask_word type: word (unsigned) access: write only mechanism: by reference The address of a word that indicates which ownership names were present in the protection string. Ownership Category Mask Value System 0000000000001111 Owner 0000000011110000 Group 0000111100000000 World 1111000000000000 end-position OpenVMS usage:word_signed type: word (signed) access: write only mechanism: by reference The number of characters from protection-string processed by LIB$PARSE_SOGW_PROT. In the case of an error in parsing the protection string, the offset to the offending location is returned. 3 LIB$PAUSE The Pause Program Execution routine suspends program execution and returns control to the calling command level. Format LIB$PAUSE 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments None. 3 LIB$POLYD The Evaluate Polynomials routine (D-floating values) allows higher-level language users to evaluate D-floating value polynomials. D-floating values are not supported in full precision in native OpenVMS Alpha and I64 programs. They are precise to 56 bits on VAX systems, 53 or 56 bits in translated VAX images, and 53 bits in native OpenVMS Alpha and I64 programs. Format LIB$POLYD polynomial-argument ,degree ,coefficient ,floating-point-result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments polynomial-argument OpenVMS usage:floating_point type: D_floating access: read only mechanism: by reference The address of a D-floating number that is the argument for the polynomial. degree OpenVMS usage:word_signed type: word integer (signed) access: read only mechanism: by reference The address of a signed word integer that is the highest-numbered nonzero coefficient to participate in the evaluation. If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. coefficient OpenVMS usage:floating_point type: D_floating access: read only mechanism: by reference, array reference The address of an array of D-floating coefficients. The coefficient of the highest-order term of the polynomial is the lowest-addressed element in the array. floating-point-result OpenVMS usage:floating_point type: D_floating access: write only mechanism: by reference The address of a floating-point number that is the result of the calculation. LIB$POLYD writes the address of floating-point- result into a D-floating number. Intermediate multiplications are carried out using extended floating-point fractions (63 bits for POLYD). 3 LIB$POLYF The Evaluate Polynomials routine (F-floating values) allows higher-level language users to evaluate F-floating polynomials. Format LIB$POLYF polynomial-argument ,degree ,coefficient ,floating-point-result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments polynomial-argument OpenVMS usage:floating_point type: F_floating access: read only mechanism: by reference Argument for the polynomial. The polynomial-argument argument is the address of a floating-point number that contains this argument. The polynomial-argument argument is an F-floating number. degree OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by reference Highest-numbered nonzero coefficient to participate in the evaluation. The degree argument is the address of a signed word integer that contains this highest-numbered coefficient. If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. coefficient OpenVMS usage:floating_point type: F_floating access: read only mechanism: by reference, array reference The address of an array of floating-point coefficients. The coefficient of the highest-order term of the polynomial is the lowest addressed element in the array. The coefficient argument is an array of F-floating numbers. floating-point-result OpenVMS usage:floating_point type: F_floating access: write only mechanism: by reference Result of the calculation. The floating-point-result argument is the address of a floating-point number that contains this result. LIB$POLYF writes the address of floating-point-result into an F-floating number. Intermediate multiplications are carried out using extended floating-point fractions (31 bits for POLYF). 3 LIB$POLYG The Evaluate Polynomials routine (G-floating values) allows higher-level language users to evaluate G-floating value polynomials. Format LIB$POLYG polynomial-argument ,degree ,coefficient ,floating-point-result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments polynomial-argument OpenVMS usage:floating_point type: G_floating access: read only mechanism: by reference Argument for the polynomial. The polynomial-argument argument is the address of a floating-point number that contains this argument. The polynomial-argument argument is a G-floating number. degree OpenVMS usage:word_signed type: word integer (signed) access: read only mechanism: by reference Highest-numbered nonzero coefficient to participate in the evaluation. The degree argument is the address of a signed word integer that contains this highest-numbered coefficient. If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. coefficient OpenVMS usage:floating_point type: G_floating access: read only mechanism: by reference, array reference Floating-point coefficients. The coefficient argument is the address of an array of floating-point coefficients. The coefficient of the highest-order term of the polynomial is the lowest addressed element in the array. The coefficient argument is an array of G-floating numbers. floating-point-result OpenVMS usage:floating_point type: G_floating access: write only mechanism: by reference Result of the calculation. The floating-point-result argument is the address of a floating-point number that contains this result. LIB$POLYG writes the address of floating-point-result into a G-floating number. Intermediate multiplications are carried out using extended floating-point fractions (63 bits for POLYG). 3 LIB$POLYH On OpenVMS VAX systems, the Evaluate Polynomials routine (H- floating values) allows higher-level language users to evaluate H-floating value polynomials. This routine is not available to native OpenVMS Alpha and I64 programs but is available to translated VAX images. Format LIB$POLYH polynomial-argument ,degree ,coefficient ,floating-point-result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments polynomial-argument OpenVMS usage:floating_point type: H_floating access: read only mechanism: by reference Argument for the polynomial. The polynomial-argument argument is the address of a floating-point number that contains this argument. The polynomial-argument argument is an H-floating number. degree OpenVMS usage:word_signed type: word integer (signed) access: read only mechanism: by reference Highest-numbered nonzero coefficient to participate in the evaluation. The degree argument is the address of a signed word integer that contains this highest-numbered coefficient. If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. coefficient OpenVMS usage:floating_point type: H_floating access: read only mechanism: by reference, array reference Floating-point coefficients. The coefficient argument is the address of an array of floating-point coefficients. The coefficient of the highest-order term of the polynomial is the lowest addressed element in the array. The coefficient argument is an array of H-floating numbers. floating-point-result OpenVMS usage:floating_point type: H_floating access: write only mechanism: by reference Result of the calculation. The floating-point-result argument is the address of a floating-point number that contains this result. LIB$POLYH writes the address of floating-point-result into an H-floating number. Intermediate multiplications are carried out using extended floating-point fractions (127 bits for POLYH). 3 LIB$POLYS (Alpha and I64 only.) The Evaluate Polynomials routine (IEEE S- floating values) allows higher-level language users to evaluate IEEE S-floating polynomials. Format LIB$POLYS polynomial-argument ,degree ,coefficient ,floating-point-result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments polynomial-argument OpenVMS usage:floating_point type: IEEE S_floating access: read only mechanism: by reference Argument for the polynomial. The polynomial-argument argument is the address of a floating-point number that contains this argument. The polynomial-argument argument is an IEEE S-floating number. degree OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by reference Highest-numbered nonzero coefficient to participate in the evaluation. The degree argument is the address of a signed word integer that contains this highest-numbered coefficient. If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. coefficient OpenVMS usage:floating_point type: IEEE S_floating access: read only mechanism: by reference, array reference The address of an array of floating-point coefficients. The coefficient of the highest-order term of the polynomial is the lowest addressed element in the array. The coefficient argument is an array of IEEE S-floating numbers. floating-point-result OpenVMS usage:floating_point type: IEEE S_floating access: write only mechanism: by reference Result of the calculation. The floating-point-result argument is the address of a floating-point number that contains this result. LIB$POLYS writes the address of floating-point-result into an IEEE S-floating number. Intermediate multiplications are carried out using extended floating-point fractions (31 bits for POLYS). 3 LIB$POLYT (Alpha and I64 only.) The Evaluate Polynomials routine (IEEE T- floating values) allows higher-level language users to evaluate IEEE T-floating polynomials. Format LIB$POLYT polynomial-argument ,degree ,coefficient ,floating-point-result 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments polynomial-argument OpenVMS usage:floating_point type: IEEE T_floating access: read only mechanism: by reference Argument for the polynomial. The polynomial-argument argument is the address of a floating-point number that contains this argument. The polynomial-argument argument is an IEEE T-floating number. degree OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by reference Highest-numbered nonzero coefficient to participate in the evaluation. The degree argument is the address of a signed word integer that contains this highest-numbered coefficient. If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. coefficient OpenVMS usage:floating_point type: IEEE T_floating access: read only mechanism: by reference, array reference The address of an array of floating-point coefficients. The coefficient of the highest-order term of the polynomial is the lowest addressed element in the array. The coefficient argument is an array of IEEE T-floating numbers. floating-point-result OpenVMS usage:floating_point type: IEEE T_floating access: write only mechanism: by reference Result of the calculation. The floating-point-result argument is the address of a floating-point number that contains this result. LIB$POLYT writes the address of floating-point-result into an IEEE T-floating number. Intermediate multiplications are carried out using extended floating-point fractions (31 bits for POLYT). 3 LIB$PUT_COMMON The Put String to Common routine copies the contents of a string into the common area. The common area is an area of storage that remains defined across multiple image activations in a process. Optionally, LIB$PUT_COMMON returns the actual number of characters copied. The maximum number of characters that can be copied is 252. Format LIB$PUT_COMMON source-string [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string to be copied to the common area by LIB$PUT_COMMON. The source-string argument is the address of a descriptor pointing to this source string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of characters copied by LIB$PUT_COMMON to the common area. The resultant-length argument is the address of an unsigned word integer that contains this number of characters. LIB$PUT_COMMON writes this number into the resultant-length argument. 3 LIB$PUT_INVO_REGISTERS (Alpha and I64 only.) The Put Invocation Registers routine modifies specified values in a procedure's invocation context. A procedure's invocation context consists of the values stored in the integer and floating-point registers as well as the program counter and the processor status registers. LIB$PUT_INVO_REGISTERS updates internal register save areas with the new values. These values are written to the active register set by the time control returns to the procedure asociated with the specified invocation handle. Format LIB$PUT_INVO_REGISTERS invo_handle, invo_context, invo_mask 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value Status value. A value of 1 indicates success. When the initial context represents the bottom of the call chain, a value of 0 is returned. 4 Arguments invo_handle OpenVMS usage:invo_handle type: longword (unsigned) access: read only mechanism: by value Handle for the invocation to be updated. invo_context OpenVMS usage:invo_context_blk type: structure access: read only mechanism: by reference Address of an invocation context block that contains the values to be written to the registers. Each register that is set in the invo_mask parameter is updated using the value found in the corresponding IREG or FREG field of the invocation context block. The program counter and processor status of the given invocation can also be updated in this way. No other fields of the invocation context block are used. invo_mask OpenVMS usage:mask_quadword type: quadword (unsigned) access: read only mechanism: by reference Address of a 64-bit vector, where each bit corresponds to a register field in the passed invo_context. Bits 0 through 29 correspond to IREG[0] through IREG[29], bit 30 corresponds to STACK_POINTER and cannot be changed, bit 31 corresponds to PROGRAM_COUNTER, bits 32 through 62 correspond to FREG[0] through FREG[30], and bit 63 corresponds to PROCESSOR_STATUS. 3 LIB$PUT_OUTPUT The Put Line to SYS$OUTPUT routine writes a record to the current controlling output device, specified by SYS$OUTPUT using the OpenVMS RMS $PUT service. Format LIB$PUT_OUTPUT message-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument message-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Message string written to the current controlling output device by LIB$PUT_OUTPUT. The message-string argument is the address of a descriptor pointing to this message string. RMS handles all formatting, so the message does not need to include such ASCII formatting instructions as carriage return (CR). 3 LIB$RADIX_POINT The Radix Point Symbol routine returns the system's radix point symbol. This symbol is used inside a digit string to separate the integer part from the fraction part. This routine works by attempting to translate the logical name SYS$RADIX_POINT as a process, group, or system logical name. Format LIB$RADIX_POINT radix-point-string [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments radix-point-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Radix point string. The radix-point-string argument is the address of a descriptor pointing to this radix point string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference The number of characters written into radix-point-string, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word that contains this number. If the radix-point-string argument is the address of a fixed- length string descriptor, there may not be enough characters in the fixed-length string to contain the whole radix point string, and the radix point string is truncated. If the radix point string is truncated to the size specified in a fixed- length string descriptor, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of radix-point-string. 3 LIB$REMQHI The Remove Entry from Head of Queue routine removes an entry from the head of the specified self-relative longword interlocked queue. LIB$REMQHI makes the REMQHI instruction available as a callable routine. Format LIB$REMQHI header ,remque-address [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments header OpenVMS usage:quadword_signed type: quadword integer (signed) access: modify mechanism: by reference Queue header specifying the queue from which entry will be removed. The header argument contains the address of this signed aligned quadword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. On Alpha and I64 systems, the header argument must contain a 32-bit address. A 64-bit address results in an illegal operand exception. remque-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Address of the removed entry. The remque-address argument is the address of an unsigned longword that contains this address. If the queue was empty, remque-address is set to the address of the header. On Alpha and I64 systems, the remque-address argument must contain a 32-bit address. A 64-bit address results in an illegal operand exception. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the operation is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of a longword that contains the retry count value. A value of 1 causes no retries. The default value is 10. 3 LIB$REMQHIQ (Alpha and I64 only.) The Remove Entry from Head of Queue routine removes an entry from the head of the specified self-relative quadword interlocked queue. LIB$REMQHIQ makes the REMQHIQ instruction available as a callable routine. Format LIB$REMQHIQ header ,remque-address [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments header OpenVMS usage:octaword_signed type: octaword integer (signed) access: modify mechanism: by reference Queue header specifying the queue from which entry will be removed. The header argument contains the address of this signed aligned octaword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. remque-address OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference Address of the removed entry. The remque-address argument is the address of an unsigned quadword that contains this address. If the queue was empty, remque-address is set to the address of the header. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the operation is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of a longword that contains the retry count value. A value of 1 causes no retries. The default value is 10. 3 LIB$REMQTI The Remove Entry from Tail of Queue routine removes an entry from the tail of the specified self-relative longword interlocked queue. LIB$REMQTI makes the REMQTI instruction available as a callable routine. Format LIB$REMQTI header ,remque-address [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments header OpenVMS usage:quadword_signed type: quadword integer (signed) access: modify mechanism: by reference Queue header specifying the queue from which the entry is to be deleted. The header argument contains the address of this signed aligned quadword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. On Alpha and I64 systems, the header argument must contain a 32- bit sign-extended address. An illegal operand exception occurs for any other form of address. remque-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Address of the removed entry. The remque-address argument is the address of a longword that contains this address. If the queue was empty, remque-address is set to the address of the header. On Alpha and I64 systems, the remque-address argument must contain a 32-bit sign-extended address. An illegal operand exception occurs for any other form of address. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the operation is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of a longword that is this retry count value. A value of 1 causes no retries. The default value is 10. 3 LIB$REMQTIQ (Alpha and I64 only.) The Remove Entry from Tail of Queue routine removes an entry from the tail of the specified self-relative quadword interlocked queue. LIB$REMQTIQ makes the REMQTIQ instruction available as a callable routine. Format LIB$REMQTIQ header ,remque-address [,retry-count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments header OpenVMS usage:octaword_signed type: octaword integer (signed) access: modify mechanism: by reference Queue header specifying the queue from which the entry is to be deleted. The header argument contains the address of this signed aligned octaword integer. The header argument must be initialized to zero before first use of the queue; zero means an empty queue. remque-address OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference Address of the removed entry. The remque-address argument is the address of a quadword that contains this address. If the queue was empty, remque-address is set to the address of the header. retry-count OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference The number of times the operation is to be retried in case of secondary-interlock failure of the queue instruction in a processor-shared memory application. The retry-count argument is the address of a longword that is this retry count value. A value of 1 causes no retries. The default value is 10. 3 LIB$RENAME_FILE The Rename One or More Files routine changes the names of one or more files. The specification of the files to be renamed can include wildcards. LIB$RENAME_FILE is similar in function to the DCL command RENAME. Format LIB$RENAME_FILE old-filespec ,new-filespec [,default-filespec] [,related-filespec] [,flags] [,user-success-procedure] [,user-error-procedure] [,user-confirm-procedure] [,user-specified-argument] [,old-resultant-name] [,new-resultant-name] [,file-scan-context] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments old-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification of the files to be renamed. The old-filespec argument is the address of a descriptor pointing to the old file specification. The specification may include wildcards, in which case each file that matches the specification will be renamed. If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string must not contain more characters than specified by NAML$C_MAXRSS, otherwise the string must not contain more than 255 characters. Any string class is supported. new-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification for the new file names. The new-filespec argument is the address of a descriptor pointing to the new file specification. This specification need not be complete; fields omitted or specified by using the wildcard character (*) will be filled in from the existing file's name using the same rules as for the DCL command RENAME. If running on Alpha or I64 and flag LIB$M_FIL_ LONG_NAMES is set, the string must not contain more characters than specified by NAML$C_MAXRSS, otherwise the string must not contain more than 255 characters. Any string class is supported. default-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Default file specification of the files to be renamed. The default-filespec argument is the address of a descriptor pointing to the default file specification. This is an optional argument; if omitted, the default is the null string. See the OpenVMS Record Management Services Reference Manual for information on default file specifications. If running on Alpha or I64 and flag LIB$M_FIL_LONG_NAMES is set, the string must not contain more characters than specified by NAML$C_MAXRSS, otherwise the string must not contain more than 255 characters. Any string class is supported. related-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Related file specification of the files to be renamed. The related-filespec argument is the address of a descriptor pointing to the related file specification. This is an optional argument; if omitted, the default is the null string. Any string class is supported. Input file parsing is used. (See the OpenVMS Record Management Services Reference Manual for information on related file specifications and input file parsing.) The related file specification is useful when you are processing lists of file specifications. Unspecified portions of the file specification are inherited from the last file processed. Any string class is supported. This is an optional argument. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Longword of flag bits designating optional behavior. The flags argument is the address of an unsigned longword containing the flag bits. This is an optional argument; if omitted, the default is that all flags are clear. The bit number and its meaning are as follows: Bit Symbol Description 0 LIB$M_FIL_CUR_VER If new-filespec does not specify a version number, this flag controls whether a new version number for the output file is to be assigned. If this bit is set, the current version number of the file is used. If this bit is clear, the file is given a version number 1 higher than any previously existing file of the same file name and file type. This is the default action. If a file already exists with the same file name, type and version number, the error RMS$_FEX is given. This flag is equivalent to the /NONEW_VERSION qualifier of the DCL command RENAME.) 1 LIB$M_FIL_INH_ Controls whether the renamed file SECUR takes on security attributes of the new location or keeps its existing security attributes. If this bit is clear, the attributes of the renamed file are inherited from the next lower version of the new file name, if any, the new parent directory, or both. If this bit is clear, the file's security attributes are not changed; this is the default action. For more information on file security, see the HP OpenVMS Guide to System Security. This flag is equivalent to the /INHERIT_SECURITY qualifier of the DCL command RENAME. 2 LIB$M_FIL_LONG_ (Alpha and I64 only) Controls whether to NAMES accept file specifications greater than 255 characters in length. If this bit is set, LIB$RENAME_FILE can process files specifications with a maximum length of NAML$C_MAXRSS characters. If this bit is clear, LIB$RENAME_FILE can process files names with a maximum length of 255 characters. user-success-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied success routine that LIB$RENAME_FILE calls after each successful rename. user-error-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied error routine that LIB$RENAME_FILE calls when it detects an error. The value returned by the error routine determines whether LIB$RENAME_FILE processes more files. user-confirm-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied confirm routine that LIB$RENAME_FILE calls before it renames a file. The value returned by the confirm routine determines whether or not LIB$RENAME_FILE renames the file. The confirm routine can be used to select specific files for renaming based on criteria such as expiration date, size, and so on. user-specified-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value Value that LIB$RENAME_FILE passes to the success, error, and confirm routines each time they are called. Whatever mechanism is used to pass user-specified-argument to LIB$RENAME_FILE is also used to pass it to the user-supplied routines. This is an optional argument; if omitted, zero is passed by value. old-resultant-name OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which LIB$RENAME_FILE copies the old resultant file specification of the last file processed. This is an optional argument. If present, it is used to store the file specification passed to the user-supplied routines instead of a default class S, type T string. Any string class is supported. If you are specifying one or more of the action routine arguments, be sure that the descriptor class used to pass resultant-name is the same as the descriptor class required by the action routine. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines, but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use. new-resultant-name OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which LIB$RENAME_FILE writes the new OpenVMS RMS resultant file specification of the last file processed. The new- resultant-name argument is the address of a descriptor pointing to the new name. This is an optional argument. If present, it is used to store the file specification passed to the user-supplied routines instead of a class S, type T string. Any string class is supported. If you are specifying one or more of the action routine arguments, be sure that the descriptor class used to pass resultant-name is the same as the descriptor class required by the action routine. For example, VAX Ada requires a class SB descriptor for string arguments to Ada routines, but will use a class A descriptor by default when calling external routines. Refer to your language manual to determine the proper descriptor class to use. file-scan-context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context for renaming a list of file specifications. The file- scan-context is the address of a longword that contains this context. You must initialize this longword to zero before the first of a series of calls to LIB$RENAME_FILE. LIB$RENAME_ FILE uses the file scan context to retain the file context for multiple input files. LIB$FILE_SCAN uses this context to retain multiple input file related file context. This is an optional argument; it need only be specified if you are using multiple input files, as the DCL command RENAME does. You may deallocate the context allocated by LIB$FILE_SCAN while processing the LIB$RENAME_FILE requests by calling LIB$FILE_SCAN_END after all calls to LIB$RENAME_FILE have been completed. See the description of LIB$FILE_SCAN for a more detailed description of this argument. 3 LIB$RESERVE_EF The Reserve Event Flag routine allocates a local event flag number specified by event-flag-number. Format LIB$RESERVE_EF event-flag-number 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument event-flag-number OpenVMS usage:ef_number type: longword (unsigned) access: read only mechanism: by reference Event flag number to be allocated by LIB$RESERVE_EF. The event- flag-number argument contains the address of a signed longword integer that is this event flag number. 3 LIB$RESET_VM_ZONE The Reset Virtual Memory Zone routine frees all blocks of memory that were previously allocated from a zone in the 32-bit virtual address space. Format LIB$RESET_VM_ZONE zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument zone-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Zone identifier. The zone-id is the address of a longword that contains the identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE. 3 LIB$RESET_VM_ZONE_64 (Alpha and I64 only.) The Reset Virtual Memory Zone routine frees all blocks of memory that were previously allocated from a zone in the 64-bit virtual address space. Format LIB$RESET_VM_ZONE_64 zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument zone-id OpenVMS usage:identifier type: quadword (unsigned) access: read only mechanism: by reference Zone identifier. The zone-id is the address of a quadword that contains the identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE_64 or LIB$CREATE_USER_VM_ZONE_64. 3 LIB$REVERT The Revert to the Handler of the Routine Activator routine deletes the condition handler established by LIB$ESTABLISH by clearing the address pointing to the condition handler from the activated routine's stack frame. This routine is not available to native OpenVMS Alpha and I64 programs but is recognized and handled appropriately by most HP high-level language compilers. Format LIB$REVERT 4 Returns OpenVMS usage:address type: address access: write only mechanism: by value Previous contents of SF$A_HANDLER (longword 0) of the caller's stack frame. This is the address of the condition handler previously in effect. If no condition handler was in effect, zero is returned. 4 Arguments None. 3 LIB$RUN_PROGRAM The Run New Program routine causes the current program to stop running and begins execution of another program. Format LIB$RUN_PROGRAM program-name 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument program-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File name of the program to be run in place of the current program. The program-name argument contains the address of a descriptor pointing to this file name string. The maximum length of the file name is 255 characters. The default file type is .EXE. 3 LIB$SCANC The Scan for Characters and Return Relative Position routine is used to find a specified set of characters in the source string. LIB$SCANC makes the VAX SCANC instruction available as a callable routine. Format LIB$SCANC source-string ,table-array ,byte-integer-mask 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Relative position in the source string of the character that terminated the operation, or zero if the terminator character is not found. If the source string has a zero length, then a zero is returned. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string used by LIB$SCANC to index into a table. The source-string argument contains the address of a descriptor pointing to this source string. table-array OpenVMS usage:vector_mask_byte type: byte (unsigned) access: read only mechanism: by reference, array reference Table that LIB$SCANC indexes into and performs a logical AND operation with the byte-integer-mask byte. The table-array argument contains the address of an unsigned byte array that is this table. byte-integer-mask OpenVMS usage:mask_byte type: byte (unsigned) access: read only mechanism: by reference Mask on which a logical AND operation is performed with bytes in table-array. The byte-integer-mask argument contains the address of an unsigned byte that is this mask. 3 LIB$SCOPY_DXDX The Copy Source String Passed by Descriptor to Destination routine copies a source string passed by descriptor to a destination string. Format LIB$SCOPY_DXDX source-string ,destination-string 4 Corresponding_JSB_Entry_Point LIB$SCOPY_DXDX6 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string to be copied to the destination string by LIB$SCOPY_DXDX. The source-string argument contains the address of a descriptor pointing to this source string. The descriptor class can be unspecified, fixed-length, decimal string, array, noncontiguous array, varying, or dynamic. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string to which the source string is copied. The destination-string argument contains the address of a descriptor pointing to this destination string. The following actions occur depending on the class of the destination string's descriptor: Descriptor Class Action S, Z, SD, A, Copy the source string. If needed, space-fill or NCA truncate on the right. D If the area specified by the destination descriptor is large enough to contain the source string, copy the source string and set the new length in the destination descriptor. If the area specified is not large enough, return the previous space allocation (if any) and then dynamically allocate the amount of space needed. Copy the source string and set the new length and address in the destination descriptor. VS Copy source string to destination string up to the limit of the descriptor MAXSTRLEN field with no padding. Readjust the current length (CURLEN) field to the actual number of bytes copied. 3 LIB$SCOPY_R_DX The Copy Source String Passed by Reference to Destination String routine copies a source string passed by reference to a destination string, passed by descriptor. Format LIB$SCOPY_R_DX word-integer-source-length ,source-string ,destination-string 4 Corresponding_JSB_Entry_Point LIB$SCOPY_R_DX6 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments word-integer-source-length OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Length of the source string in bytes. The word-integer-source- length argument is the address of an unsigned word that contains the length of the source string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by reference Source string to be copied to the destination string by LIB$SCOPY_R_DX. The source-string argument is the address of this source string. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string to which the source string is copied. The destination-string argument contains the address of a descriptor pointing to this destination string. 3 LIB$SCOPY_R_DX_64 (Alpha and I64 only.) The Copy Source String Passed by Reference to Destination String routine copies a source string passed by reference to a destination string, passed by descriptor. Format LIB$SCOPY_R_DX_64 quad-integer-source-length ,source-string ,destination-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments quad-integer-source-length OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: read only mechanism: by reference Length of the source string in bytes. The quad-integer-source- length argument is the address of an unsigned quadword that contains the length of the source string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by reference Source string to be copied to the destination string by LIB$SCOPY_R_DX_64. The source-string argument is the address of this source string. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string to which the source string is copied. The destination-string argument contains the address of a descriptor pointing to this destination string. 3 LIB$SET_LOGICAL The Set Logical Name routine requests the calling process's command language interpreter (CLI) to define or redefine a supervisor-mode process logical name. It provides the same function as the DCL command DEFINE. Format LIB$SET_LOGICAL logical-name [,value-string] [,table] [,attributes] [,item-list] Either the item-list or value-string argument must be specified. If both item-list and value-string are specified, the value-string argument is ignored. 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments logical-name OpenVMS usage:logical_name type: character string access: read only mechanism: by descriptor Logical name to be defined or redefined. The logical-name argument contains the address of a descriptor pointing to this logical name string. The maximum length of a logical name is 255 characters. Note that logical names are case sensitive. value-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Value to be given to the logical name. The value-string argument contains the address of a descriptor pointing to this value string. The maximum length of a logical name value is 255 characters. If omitted, an item list must be present to specify the values of the logical name. table OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the table in which to create the logical name. The table argument contains the address of a descriptor pointing to the logical name table. If no table is specified, LNM$PROCESS is used as the default. attributes OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Logical name or translation attributes. The attributes argument is the address of a longword bit mask that contains the logical name or translation attributes. LNM$M_CONFINE and LNM$M_NO_ALIAS are currently available logical name attributes. See the description of the $CRELNM system service in the HP OpenVMS System Services Reference Manual: A- GETUAI for definitions of LNM$M_CONFINE and LNM$M_NO_ALIAS. If omitted, no special logical name attribute is established. If no item-list is specified, the translation attributes LNM$M_CONCEALED and LNM$M_TERMINAL may be specified. See the description of the ASSIGN command in the HP OpenVMS DCL Dictionary for definitions of these attributes. If an item-list is specified, it will contain the translation attributes for each equivalence string in the attribute. item-list OpenVMS usage:item_list_3 type: unspecified access: read only mechanism: by reference, array reference Item list describing the equivalence names for this logical name. The item-list argument contains the address of an array that contains this item list. If item-list is not specified, the logical name will have only one value, as specified in the value-string argument. Item codes for use with this item list are included in libraries supplied by HP in module $LNMDEF. Either value-string or item-list must be specified. If neither is specified, the LIB$_INVARG error is produced. If both value- string and item-list are specified, the value-string argument is ignored. If item-list is specified, only logical name attributes are permitted. Translation attributes appear in the item list. The item-list argument is needed only when you want to create multiple equivalence strings for a single logical name. 3 LIB$SET_SYMBOL The Set Value of CLI Symbol routine requests the calling process's command language interpreter (CLI) to define or redefine a CLI symbol. Format LIB$SET_SYMBOL symbol ,value-string [,table-type-indicator] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments symbol OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Name of the symbol to be defined or modified by LIB$SET_SYMBOL. The symbol argument is the address of a descriptor pointing to this symbol string. If you redefine a previously defined CLI symbol, the symbol value is modified to the new value that you provide. The symbol name is converted to uppercase and trailing blanks are removed before use. The symbol argument must begin with a letter, a digit, a dollar sign ($), a hyphen (-), or an underscore (_). The maximum length of symbol is 255 characters. value-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Value to be given to the symbol. The value-string argument is the address of a descriptor pointing to this value string. Trailing blanks are not removed from the value string before use. The maximum length of value-string is 1024 characters. Integer values are not allowed; LIB$SET_SYMBOL is intended to set string CLI symbols, not integer CLI symbols. table-type-indicator OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Indicator of the table that will contain the defined symbol. The table-type-indicator argument is the address of a signed longword integer that is this table indicator. If omitted, the local symbol table is used. The following are possible values for table-type-indicator: Symbolic Name Value Table Used LIB$K_CLI_LOCAL_ 1 Local symbol table SYM LIB$K_CLI_GLOBAL_ 2 Global symbol table SYM 3 LIB$SFREE1_DD The Free One Dynamic String routine returns the dynamically allocated storage for a dynamic string. Format LIB$SFREE1_DD descriptor-address 4 Corresponding_JSB_Entry_Point LIB$SFREE1_DD6 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument descriptor-address OpenVMS usage:descriptor type: quadword (unsigned) access: modify mechanism: by reference Dynamic descriptor specifying the area to be deallocated. The descriptor-address argument is the address of an unsigned quadword that is this descriptor. The descriptor is assumed to be dynamic and its class field is not checked. 3 LIB$SFREEN_DD The Free One or More Dynamic Strings routine returns one or more dynamic strings to free storage. Format LIB$SFREEN_DD number-of-descriptors ,first-descriptor-array 4 Corresponding_JSB_Entry_Point LIB$SFREEN_DD6 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-descriptors OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Number of adjacent descriptors freed by LIB$SFREEN_DD. The number-of-descriptors argument contains the address of an unsigned longword that is this number. The deallocated area is returned to free storage. first-descriptor-array OpenVMS usage:descriptor_array type: quadword (unsigned) access: modify mechanism: by reference, array reference First descriptor of an array of descriptors. The first- descriptor-array argument contains the address of this first descriptor. The descriptors are assumed to be dynamic, and their class fields are not checked. The descriptor array must contain all 32-bit descriptors or all 64-bit descriptors. They cannot be mixed. 3 LIB$SGET1_DD The Get One Dynamic String routine allocates dynamic virtual memory to the string descriptor you specify. Format LIB$SGET1_DD word-integer-length ,descriptor-part 4 Corresponding_JSB_Entry_Point LIB$SGET1_DD_R6 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments word-integer-length OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Number of bytes of dynamic virtual memory to be allocated by LIB$SGET1_DD. The word-integer-length argument is the address of an unsigned word that contains this number. The amount of storage allocated may be rounded up automatically. descriptor-part OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: write only mechanism: by reference Descriptor of the dynamic string to which LIB$SGET1_DD allocates the dynamic virtual memory. The descriptor-part argument contains the address of this descriptor. The descriptor-part argument must contain the address of a dynamic string descriptor; LIB$SGET1_DD returns an unpredictable result if any other type of descriptor is specified by this argument. The descriptor CLASS field is not checked but is set to dynamic (2). The LENGTH field is set to word-integer-length, and the POINTER field points to the string area allocated. 3 LIB$SGET1_DD_64 (Alpha and I64 only.) The Get One Dynamic String routine allocates dynamic virtual memory to the string descriptor you specify. Format LIB$SGET1_DD_64 quad-integer-length ,descriptor-part 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments quad-integer-length OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: read only mechanism: by reference Number of bytes of dynamic virtual memory to be allocated by LIB$SGET1_DD_64. The quad-integer-length argument is the address of an unsigned quadword that contains this number. The amount of storage allocated can be rounded up automatically. descriptor-part OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: write only mechanism: by reference Descriptor of the dynamic string to which LIB$SGET1_DD_64 allocates the dynamic virtual memory. The descriptor-part argument contains the address of this descriptor. The descriptor-part argument must contain the address of a dynamic string descriptor; LIB$SGET1_DD_64 returns an unpredictable result if any other type of descriptor is specified by this argument. The descriptor CLASS field is not checked but is set to dynamic (2). The LENGTH field is set to quad-integer-length, and the POINTER field points to the string area allocated. 3 LIB$SHOW_TIMER The Show Accumulated Times and Counts routine returns times and counts accumulated since the last call to LIB$INIT_TIMER and displays them on SYS$OUTPUT. (LIB$INIT_TIMER must be called prior to invoking this routine.) A user-supplied action routine may change this default behavior. Format LIB$SHOW_TIMER [handle-address] [,code] [,user-action-procedure] [,user-argument-value] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments handle-address OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Block of storage containing the value returned by a previous call to LIB$INIT_TIMER. The handle-address argument is the address of an unsigned longword integer containing that value. o If specified, the pointer must be the same value returned by a previous call to LIB$INIT_TIMER. o If omitted, LIB$SHOW_TIMER will use a block of memory allocated by LIB$INIT_TIMER. o If handle-address is omitted and LIB$INIT_TIMER has not been called previously, the error LIB$_INVARG is returned. LIB$INIT_TIMER must be called prior to a call to LIB$SHOW_ TIMER. Note that the handle-address argument is the same as the context argument used in the LIB$INIT_TIMER call. LIB$SHOW_TIMER assumes that LIB$INIT_TIMER has been previously called, and that the results of that call are stored either in a block pointed to by handle-address, or in the memory allocated by LIB$INIT_TIMER. code OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Integer specifying the statistic you want; if it is omitted or zero, all five statistics are returned on one line. The code argument is the address of a signed longword integer containing the statistic code. The following values are allowed for the code argument: Value Description 1 Elapsed time 2 CPU time 3 Buffered I/O 4 Direct I/O 5 Page faults user-action-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied action routine called by LIB$SHOW_TIMER. The default action of LIB$SHOW_TIMER is to write the results to SYS$OUTPUT. An action routine is useful if you want to write the results to a file or, in general, anywhere other than SYS$OUTPUT. The action routine returns either a success or failure condition value; this status is returned to the calling program as the value of LIB$SHOW_TIMER. user-argument-value OpenVMS usage:user-arg type: longword (unsigned) (on VAX systems) quadword (unsigned) (on Alpha and I64 systems) access: read only mechanism: by value A value to be passed to the action routine without interpretation. If omitted, LIB$SHOW_TIMER passes a zero by value to the user routine. 3 LIB$SHOW_VM The Show Virtual Memory Statistics routine returns the statistics accumulated from calls to LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_ PAGE/LIB$FREE_VM_PAGE. Format LIB$SHOW_VM [code] [,user-action-procedure] [,user-specified-argument] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments code OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Code specifying any one of the statistics to be written to SYS$OUTPUT or passed to an action routine for processing. The code argument is the address of a signed longword integer containing the statistic code. This is an optional argument. If the statistic code is omitted or is zero, statistics for values 1, 2, and 3 are returned on one line. The following values are allowed for the code argument: Value Statistic 0 Statistics for values 1, 2, and 3 are returned. 1 Number of successful calls to LIB$GET_VM. 2 Number of successful calls to LIB$FREE_VM. 3 Number of bytes allocated by LIB$GET_VM but not yet deallocated by LIB$FREE_VM. 4 Statistics for values 5, 6, and 7 are returned. 5 Number of calls to LIB$GET_VM_PAGE. 6 Number of calls to LIB$FREE_VM_PAGE. 7 Number of VAX pages or Alpha pagelets allocated by LIB$GET_ VM_PAGE but not yet deallocated by LIB$FREE_VM_PAGE. user-action-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied action routine called by LIB$SHOW_VM. By default, LIB$SHOW_VM returns statistics to SYS$OUTPUT. An action routine is useful when you want to return statistics to a file or, in general, to any place other than SYS$OUTPUT. The routine returns either a success or failure condition value, which will be returned as the value of LIB$SHOW_VM. user-specified-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value A 32-bit value to be passed directly to the action routine without interpretation. That is, the contents of the argument list entry user-specified-argument are copied to the argument list entry for user-action-procedure. 3 LIB$SHOW_VM_64 (Alpha and I64 only.) The Show Virtual Memory Statistics routine returns the statistics accumulated from calls to LIB$GET_VM_ 64/LIB$FREE_VM_64 and LIB$GET_VM_PAGE_64/LIB$FREE_VM_PAGE_64. Format LIB$SHOW_VM_64 [code] [,user-action-procedure] [,user-specified-argument] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments code OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Code specifying any one of the statistics to be written to SYS$OUTPUT or passed to an action routine for processing. The code argument is the address of a signed quadword integer containing the statistic code. This is an optional argument. If the statistic code is omitted or is zero, statistics for values 1, 2, and 3 are returned on one line. The following values are allowed for the code argument: Value Statistic 0 Statistics for values 1, 2, and 3 are returned. 1 Number of successful calls to LIB$GET_VM_64. 2 Number of successful calls to LIB$FREE_VM_64. 3 Number of bytes allocated by LIB$GET_VM_64 but not yet deallocated by LIB$FREE_VM_64. 4 Statistics for values 5, 6, and 7 are returned. 5 Number of calls to LIB$GET_VM_PAGE_64. 6 Number of calls to LIB$FREE_VM_PAGE_64. 7 Number of Alpha or I64 pagelets allocated by LIB$GET_VM_ PAGE_64 but not yet deallocated by LIB$FREE_VM_PAGE_64. user-action-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied action routine called by LIB$SHOW_VM_64. By default, LIB$SHOW_VM_64 returns statistics to SYS$OUTPUT. An action routine is useful when you want to return statistics to a file or, in general, to any place other than SYS$OUTPUT. The routine returns either a success or failure condition value, which will be returned as the value of LIB$SHOW_VM_64. user-specified-argument OpenVMS usage:user_arg type: quadword (unsigned) access: read only mechanism: by value A 64-bit value to be passed directly to the action routine without interpretation. That is, the contents of the argument list entry user-specified-argument are copied to the argument list entry for user-action-procedure. 3 LIB$SHOW_VM_ZONE The Return Information About a Zone routine returns formatted information about a zone in the 32-bit virtual address space, detailing such information as the zone's name, characteristics, and areas, and then passes the information to the specified or default action routine. Format LIB$SHOW_VM_ZONE zone-id [,detail-level] [,user-action-procedure] [,user-arg] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments zone-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Zone identifier. The zone-id argument is the address of an unsigned longword containing this identifier. Use zero to indicate the 32-bit default zone. detail-level OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference An identifier code specifying the level of detail required by the user. The detail-level argument is the address of a signed longword containing this code. The default is minimal information. The following are valid values for detail-level: 0 zone-id and name 1 zone-id, name, algorithm, flags, and size information 2 zone-id, name, algorithm, flags, size information, cache information, and area summary 3 zone-id, name, algorithm, flags, size information, cache information, area summary, and queue validation user-action-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value Optional user-supplied action routine called by LIB$SHOW_VM_ZONE. By default, LIB$SHOW_VM_ZONE prints statistics to SYS$OUTPUT by means of LIB$PUT_OUTPUT. An action routine is useful when you want to return statistics to a file or, in general, to any location other than SYS$OUTPUT. If user-action-procedure fails, LIB$SHOW_VM_ZONE terminates and returns a failure code. Success codes are ignored. user-arg OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value Optional 32-bit value to be passed directly to the action routine without interpretation. That is, the contents of the argument list entry user-arg are copied to the argument list entry for user-action-procedure. 3 LIB$SHOW_VM_ZONE_64 (Alpha and I64 only.) The Return Information About a Zone routine returns formatted information about a zone in the 64-bit virtual address space, detailing such information as the zone's name, characteristics, and areas, and then passes the information to the specified or default action routine. Format LIB$SHOW_VM_ZONE_64 zone-id [,detail-level] [,user-action-procedure] [,user-arg] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments zone-id OpenVMS usage:identifier type: quadword (unsigned) access: read only mechanism: by reference Zone identifier. The zone-id argument is the address of an unsigned quadword containing this identifier. Use zero to indicate the 64-bit default zone. detail-level OpenVMS usage:quadword_signed type: quadword (signed) access: read only mechanism: by reference An identifier code specifying the level of detail required by the user. The detail-level argument is the address of a signed quadword containing this code. The default is minimal information. The following are valid values for detail-level: 0 zone-id and name 1 zone-id, name, algorithm, flags, and size information 2 zone-id, name, algorithm, flags, size information, cache information, and area summary 3 zone-id, name, algorithm, flags, size information, cache information, area summary, and queue validation user-action-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value Optional user-supplied action routine called by LIB$SHOW_VM_ ZONE_64. By default, LIB$SHOW_VM_ZONE_64 prints statistics to SYS$OUTPUT by means of LIB$PUT_OUTPUT. An action routine is useful when you want to return statistics to a file or, in general, to any location other than SYS$OUTPUT. If user-action- procedure fails, LIB$SHOW_VM_ZONE_64 terminates and returns a failure code. Success codes are ignored. user-arg OpenVMS usage:user_arg type: quadword (unsigned) access: read only mechanism: by value Optional 64-bit value to be passed directly to the action routine without interpretation. That is, the contents of the argument list entry user-arg are copied to the argument list entry for user-action-procedure. 3 LIB$SIGNAL The Signal Exception Condition routine generates a signal that indicates that an exception condition has occurred in your program. If a condition handler does not take corrective action and the condition is severe, then your program will exit. Format LIB$SIGNAL condition-value [,condition-argument...] [,condition-value-n [,condition-argument-n...]...] 4 Returns None. 4 Arguments condition-value OpenVMS usage:cond_value type: longword (unsigned) access: read only mechanism: by value OpenVMS 32-bit condition value. The condition-value argument is an unsigned longword that contains this condition value. The HP OpenVMS Programming Concepts Manual explains the format of an OpenVMS condition value. condition-argument OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by value As many arguments as are required to process the exception specified by condition-value. Note that these arguments are also used as FAO (formatted ASCII output) arguments to format a message. The HP OpenVMS Programming Concepts Manual explains the message format. condition-value-n OpenVMS usage:cond_value type: longword (unsigned) access: read only mechanism: by value OpenVMS 32-bit condition value. The optional condition-value-n argument is an unsigned longword that contains this condition value. The calling routine can specify additional conditions to be processed by specifying condition-value-2 through condition- value-n, with each condition value followed by any arguments required to process the condition specified. However, the total number of arguments in the call to LIB$SIGNAL must not exceed 253. The HP OpenVMS Programming Concepts Manual explains the format of an OpenVMS condition value. condition-argument-n OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by value As many arguments as are required to create the message reporting the exception specified by condition-value-n. The HP OpenVMS Programming Concepts Manual explains the message format. 3 LIB$SIG_TO_RET The Signal Converted to a Return Status routine converts any signaled condition value to a value returned as a function. The signaled condition is returned to the caller of the user routine that established the handler that is calling LIB$SIG_TO_RET. This routine may be established as or called from a condition handler. Format LIB$SIG_TO_RET signal-arguments ,mechanism-arguments 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments signal-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference Signal argument vector. The signal-arguments argument contains the address of an array that is this signal argument vector stack. See the HP OpenVMS Programming Concepts Manual for a description of the signal argument vector. mechanism-arguments OpenVMS usage:structure type: unspecified access: read only mechanism: by reference Mechanism arguments vector. The mechanism-arguments argument contains the address of a structure that is this mechanism argument vector stack. See the HP OpenVMS Programming Concepts Manual for a description of the mechanism argument vector. 3 LIB$SIG_TO_STOP The Convert a Signaled Condition to a Signaled Stop routine converts a signaled condition to a signaled condition that cannot be continued. Format LIB$SIG_TO_STOP signal-arguments ,mechanism-arguments 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments signal-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: modify mechanism: by reference, array reference Signal argument vector. The signal-arguments argument contains the address of an array that is this signal argument vector stack. See the HP OpenVMS Programming Concepts Manual for a description of the signal argument vector. mechanism-arguments OpenVMS usage:structure type: unspecified access: read only mechanism: by reference Mechanism argument vector. The mechanism-arguments argument contains the address of a structure that is this mechanism argument vector stack. See the HP OpenVMS Programming Concepts Manual for a description of the mechanism argument vector. 3 LIB$SIM_TRAP The Simulate Floating Trap routine converts floating faults to floating traps. It can be enabled as a condition handler or can be called by one. This routine is not available to native OpenVMS Alpha or I64 programs but is available to translated VAX images. Format LIB$SIM_TRAP signal-arguments ,mechanism-arguments 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments signal-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: modify mechanism: by reference, array reference Signal argument vector. The signal-arguments argument contains the address of an array that is this signal argument vector stack. See the HP OpenVMS Programming Concepts Manual for a description of the signal argument vector. mechanism-arguments OpenVMS usage:vector_longword_unsigned type: unspecified access: read only mechanism: by reference, array reference Mechanism argument vector. The mechanism-arguments argument contains the address of an array that is this mechanism argument vector stack. See the HP OpenVMS Programming Concepts Manual for a description of the mechanism argument vector. 3 LIB$SKPC The Skip Equal Characters routine compares each character of a given string with a given character and returns the relative position of the first nonequal character as an index. LIB$SKPC makes the VAX SKPC instruction available as a callable routine. Format LIB$SKPC character-string ,source-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value The relative position in the source string of the first unequal character. LIB$SKPC returns a zero if the source string was of zero length or if every character in source-string was equal to character-string. 4 Arguments character-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String whose initial character is to be used by LIB$SKPC in the comparison. The character-string argument contains the address of a descriptor pointing to this string. Only the first character of character-string is used, and the length of character-string is not checked. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String to be searched by LIB$SKPC. The source-string argument contains the address of a descriptor pointing to this string. 3 LIB$SPANC The Skip Selected Characters routine is used to skip a specified set of characters in the source string. LIB$SPANC makes the VAX SPANC instruction available as a callable routine. Format LIB$SPANC source-string ,table-array ,byte-integer-mask 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value The relative position in the source string of the character that terminated the operation is returned if such a character is found. Otherwise, zero is returned. If the source string has a zero length, then a zero is returned. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string used by LIB$SPANC to index into table-array. The source-string argument contains the address of a descriptor pointing to this source string. table-array OpenVMS usage:vector_mask_byte type: byte (unsigned) access: read only mechanism: by reference, array reference Table that LIB$SPANC indexes into and performs an AND operation with the byte-integer-mask byte. The table-array argument contains the address of an unsigned byte array that is this table. byte-integer-mask OpenVMS usage:mask_byte type: byte (unsigned) access: read only mechanism: by reference Mask that an AND operation is performed with bytes in table- array. The byte-integer-mask argument contains the address of an unsigned byte that is this mask. 3 LIB$SPAWN The Spawn Subprocess routine requests the command language interpreter (CLI) of the calling process to spawn a subprocess for executing CLI commands. LIB$SPAWN provides the same function as the DCL command SPAWN. Format LIB$SPAWN [command-string] [,input-file] [,output-file] [,flags] [,process-name] [,process-id] [,completion-status-address] [,byte-integer-event-flag-num] [,AST-address] [,varying-AST-argument] [,prompt-string] [,cli] [,table] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments command-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor CLI command to be executed by the spawned subprocess. The command-string argument is the address of a descriptor pointing to this CLI command string. If command-string is omitted, commands are taken from the file specified by input-file. input-file OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Equivalence name to be associated with the logical name SYS$INPUT in the logical name table for the subprocess. The input- file argument is the address of a descriptor pointing to this equivalence string. If input-file is omitted, the default is the caller's SYS$INPUT. output-file OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Equivalence name to be associated with the logical names SYS$OUTPUT and SYS$ERROR in the logical name table for the subprocess. The output-file argument is the address of a descriptor pointing to this equivalence string. If output-file is omitted, the default is the caller's SYS$OUTPUT. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Flag bits that designate optional behavior. The flags argument is the address of an unsigned longword that contains these flag bits. By default, all flags are clear. These flags are defined as follows: Bit Symbol Meaning 0 NOWAIT If this bit is set, the calling process continues executing in parallel with the subprocess. If this bit is clear, the calling process hibernates until the subprocess completes. 1 NOCLISYM If this bit is set, the spawned subprocess does not inherit CLI symbols from its caller. If this bit is clear, the subprocess inherits all currently defined CLI symbols. You may want to specify NOCLISYM to help prevent commands redefined by symbol assignments from affecting the spawned commands. 2 NOLOGNAM If this bit is set, the spawned subprocess does not inherit process logical names from its caller. If this bit is clear, the subprocess inherits all currently defined process logical names. You may want to specify NOLOGNAM to help prevent commands redefined by logical name assignments from affecting the spawned commands. 3 NOKEYPAD If this bit is set, the keypad symbols and state are not passed to the subprocess. If this bit is not set, the keypad settings are passed to the subprocess. 4 NOTIFY If this bit is set, a message is broadcast to SYS$OUTPUT when the subprocess completes or aborts. If this bit is not set, no message is broadcast. This bit should not be set unless the NOWAIT bit is also set. 5 NOCONTROL If this bit is set, no carriage-return/line-feed is prefixed to any prompt string. If this bit is not set, a carriage-return/line-feed is prefixed to any prompt string specified. 6 TRUSTED If this bit is set, it indicates a SPAWN command on behalf of the application. If this bit is not set, it indicates that the SPAWN command originates from user. SPAWN commands originating from users are disallowed in captive accounts (DCL). 7 AUTHPRIV If this bit is set, the subprocess inherits the caller's authorized privileges. If this bit is clear, the spawned processes' authorized mask is set equal to the caller's current (active) privilege mask. 8 SUBSYSTEM If this bit is set, a spawned process inherits protected subsystem IDs for the duration of LOGINOUT.EXE (used to map the CLI). The IDs will be removed in the process of transferring control to the CLI (as a user mode $RUNDWN is performed). If this bit is clear, LOGINOUT does not execute under the subsystem IDs. Bits 9 through 31 are reserved for future expansion and must be zero. Symbolic flag names are defined in libraries supplied by HP in module $CLIDEF. They are CLI$M_NOWAIT, CLI$M_NOCLISYM, CLI$M_ NOLOGNAM, CLI$M_NOKEYPAD, CLI$M_NOTIFY, CLI$M_NOCONTROL, CLI$M_ TRUSTED, CLI$M_AUTHPRIV, and CLI$M_SUBSYSTEM. process-name OpenVMS usage:process_name type: character string access: read only mechanism: by descriptor Name defined for the subprocess. The process-name argument is the address of a descriptor pointing to this name string. If process- name is omitted, a unique process name will be generated. If you supply a name and it is not unique, LIB$SPAWN will return the condition value SS$_DUPLNAM. The DCL_CTLFLAGS is a bitmask used to alter default behavior for certain commands on a systemwide basis. Currently, only the low bit of the bitmask is defined. The low bit controls the default process-name assignment for a subprocess created using the LIB$SPAWN routine. Prior to OpenVMS Version 7.3-1, if no process name was supplied, the system constructed a name by appending _n to the username, where n was the next available non-duplicate integer for any process currently in the system. For example, the first spawned process from user SYSTEM would be called SYSTEM_1, the second, SYSTEM_2, and so on. The next available number was chosen, as soon as a gap was found. Beginning in OpenVMS Version 7.3-1, the default constructed process name for subprocesses has changed. Instead of incrementally searching for the next unique number, a random number is chosen to append to the username. Therefore, the first processes that are spawned from user SYSTEM might be SYSTEM_154, SYSTEM_42, SYSTEM_87, and so on. This procedure results in a very high probability of finding a unique number on the first try since it is unlikely the same number is already in use. However, some applications might rely on the previous method of assigning subprocess names. The DCL_CTLFLAGS parameter is available to allow you to configure the system as necessary. Bit 0 of DCL_CTLFLAGS selects the behavior for assigning default subprocess names, as explained in the following: o If clear, the new behavior is used. If the process name is not specified, it will be the username with a random number suffix. This is the default setting. o If set, the previous behavior is used. If the process name is not specified, it will be the username with the next available number suffix. process-id OpenVMS usage:process_id type: longword (unsigned) access: write only mechanism: by reference Process identification of the spawned subprocess. The process-id argument is the address of an unsigned longword that contains this process identification value. This process identification value is meaningful only if the NOWAIT flags bit is set. completion-status-address OpenVMS usage:address type: address access: read only mechanism: by value The final completion status of the subprocess. The completion- status-address argument contains the address of the status. The system writes the value of the final completion status of the subprocess into completion-status-address when the subprocess completes. If the subprocess returns a status code of 0, the system writes SS$_NORMAL into this address. If the NOWAIT flags bit is set, the completion-status-address is updated asynchronously when the subprocess completes. Use the byte-integer-event-flag-num or AST-address arguments to determine when the subprocess has completed. Your program must ensure that the address is still valid when the value is written. byte-integer-event-flag-num OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference The number of a local event flag to be set when the spawned subprocess completes. The byte-integer-event-flag-num argument is the address of an unsigned byte that contains this event flag number. If byte-integer-event-flag-num is omitted, no event flag is set. Specifying byte-integer-event-flag-num is meaningful only if the NOWAIT flags bit is set. AST-address OpenVMS usage:procedure type: procedure value access: call without stack unwinding mechanism: by value Routine to be called by means of an AST when the subprocess completes. Specifying AST-address is meaningful only if the NOWAIT flags bit is set. varying-AST-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value A value to be passed to the AST routine. Typically, the varying- AST-argument argument is the address of a block of storage the AST routine will use. Specifying varying-AST-argument is meaningful only if the NOWAIT flags bit is set and if AST-address has been specified. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Prompt string to use in the subprocess. The prompt-string argument is the address of a descriptor pointing to this prompt string. If prompt-string is omitted, the subprocess uses the same prompt string that the parent process uses. cli OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification for the command language interpreter (CLI) to be run in the subprocess. The cli argument is the address of this file specification string's descriptor. The CLI specified must reside in SYS$SYSTEM with a file type of .EXE, and it must be installed. No directory or file type may be specified. The cli argument must be specified in uppercase characters. If cli is omitted, the subprocess uses the same CLI as the parent process. If cli is specified, no context is copied to the subprocess. table OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification for the command tables to be used by the spawned process. The table argument is the address of this file specification string's descriptor. The table specified must reside in SYS$SHARE with a file type of .EXE, and it must be installed. If table is omitted, the subprocess uses the same table as the parent process. 3 LIB$STAT_TIMER The Statistics, Return Accumulated Times and Counts routine returns to its caller one of five available statistics accumulated since the last call to LIB$INIT_TIMER. Unlike LIB$SHOW_TIMER, which formats the values for output, LIB$STAT_ TIMER returns the value as an unsigned longword or quadword. Format LIB$STAT_TIMER code ,value-argument [,handle-address] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments code OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference The address of a signed longword integer that contains a code to specify the statistic to be returned. The code specification must be an integer from 1 to 5. The following values are allowed for code: Value Statistic Returned 1 Elapsed real time (quadword, in system time format) 2 Elapsed CPU time (longword, in 10 millisecond increments) 3 Count of buffered I/O operations (longword) 4 Count of direct I/O operations (longword) 5 Count of page faults (longword) value-argument OpenVMS usage:user_arg type: unspecified access: write only mechanism: by reference The statistic returned by LIB$STAT_TIMER. The value-argument argument contains the address of a longword or quadword that is this statistic. All statistics are longword integers except elapsed real time, which is a quadword. See the HP OpenVMS System Services Reference Manual for more details on the system time format. handle-address OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Pointer to a block of storage. The optional handle-address argument contains the address of an unsigned longword that is this pointer. If handle-address is specified, LIB$STAT_TIMER assumes that LIB$INIT_TIMER has been called with the same value of handle- address. Handle-address is an optional argument. If it is not specified, LIB$STAT_TIMER uses internal storage. 3 LIB$STAT_VM The Return Virtual Memory Statistics routine returns to its caller one of six statistics available from calls to LIB$GET_ VM/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. Unlike LIB$SHOW_VM, which formats the values for output and displays them on SYS$OUTPUT, LIB$STAT_VM returns the statistic in the value-argument argument. Only one of the statistics is returned by each call to LIB$STAT_VM. Format LIB$STAT_VM code ,value-argument 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments code OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Code specifying which statistic is to be returned. The code argument contains the address of a signed longword integer that is this code. Code Statistic 1 Number of successful calls to LIB$GET_VM 2 Number of successful calls to LIB$FREE_VM 3 Number of bytes allocated by LIB$GET_VM but not yet deallocated by LIB$FREE_VM 5 Number of calls to LIB$GET_VM_PAGE 6 Number of calls to LIB$FREE_VM_PAGE 7 Number of VAX pages or Alpha pagelets allocated by LIB$GET_ VM_PAGE but not yet deallocated by LIB$FREE_VM_PAGE Note that it is invalid to omit code or to give a code of 0 or 4. value-argument OpenVMS usage:user_arg type: longword (unsigned) access: write only mechanism: by reference Value of the statistic returned by LIB$STAT_VM. The value- argument argument contains the address of an unsigned longword integer that is this value. 3 LIB$STAT_VM_64 (Alpha and I64 only.) The Return Virtual Memory Statistics routine returns to its caller one of six statistics available from calls to LIB$GET_VM_64 and LIB$FREE_VM_64, as well as LIB$GET_VM_PAGE_64 and LIB$FREE_VM_PAGE_64. Unlike LIB$SHOW_ VM_64, which formats the values for output and displays them on SYS$OUTPUT, LIB$STAT_VM_64 returns the statistic in the value- argument argument. Only one of the statistics is returned by each call to LIB$STAT_VM_64. Format LIB$STAT_VM_64 code ,value-argument 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments code OpenVMS usage:quadword_signed type: quadword integer (signed) access: read only mechanism: by reference Code specifying which statistic is to be returned. The code argument contains the address of a signed quadword integer that is this code. Code Statistic 1 Number of successful calls to LIB$GET_VM_64 2 Number of successful calls to LIB$FREE_VM_64 3 Number of bytes allocated by LIB$GET_VM_64 but not yet deallocated by LIB$FREE_VM_64 5 Number of calls to LIB$GET_VM_PAGE_64 6 Number of calls to LIB$FREE_VM_PAGE_64 7 Number of Alpha or I64 pagelets allocated by LIB$GET_VM_ PAGE_64 but not yet deallocated by LIB$FREE_VM_PAGE_64 Note that it is invalid to omit code or to give a code of 0 or 4. value-argument OpenVMS usage:user_arg type: quadword (unsigned) access: write only mechanism: by reference Value of the statistic returned by LIB$STAT_VM_64. The value- argument argument contains the address of an unsigned quadword integer that is this value. 3 LIB$STOP The Stop Execution and Signal the Condition routine generates a signal that indicates that an exception condition has occurred in your program. Exception conditions signaled by LIB$STOP cannot be continued from the point of the signal. Format LIB$STOP condition-value [,number-of-arguments] [,FAO-argument...] 4 Returns LIB$STOP generates a signal and stops execution of the calling program. No condition values are returned. 4 Arguments condition-value OpenVMS usage:cond_value type: longword (unsigned) access: read only mechanism: by value OpenVMS 32-bit condition value. The condition-value argument is an unsigned longword that contains this condition value. The HP OpenVMS Programming Concepts Manual explains the format of a condition value. number-of-arguments OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by value Number of FAO arguments associated with condition-value. The optional number-of-arguments argument is a signed longword integer that contains this number. If omitted or specified as zero, no FAO arguments follow. FAO-argument OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by value Optional FAO (formatted ASCII output) argument that is associated with the specified condition value. The HP OpenVMS Programming Concepts Manual explains the message format. 3 LIB$SUBX The Multiple-Precision Binary Subtraction routine performs subtraction on signed two's complement integers of arbitrary length. Format LIB$SUBX minuend-array ,subtrahend-array ,difference-array [,array-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments minuend-array OpenVMS usage:vector_longword_signed type: unspecified access: read only mechanism: by reference, array reference Minuend; a multiple-precision, signed two's complement integer. The minuend-array argument is the address of an array of signed longword integers that contains the minuend. subtrahend-array OpenVMS usage:vector_longword_signed type: unspecified access: read only mechanism: by reference, array reference Subtrahend; a multiple-precision, signed two's complement integer. The subtrahend-array argument is the address of an array of signed longword integers that contains the subtrahend. difference-array OpenVMS usage:vector_longword_signed type: unspecified access: write only mechanism: by reference, array reference Difference; a multiple-precision, signed two's complement integer result. The difference-array argument is the address of an array of signed longword integers that contains the difference. array-length OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Length in longwords of the arrays to be operated on by LIB$SUBX. The array-length argument contains the address of a signed longword integer that is this length. The array-length argument must not be negative. The default length is 2 units. 3 LIB$SUB_TIMES The Subtract Two Quadword Times routine subtracts two OpenVMS internal-time-format times. Format LIB$SUB_TIMES time1 ,time2 ,resultant-time 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments time1 OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference First time, from which LIB$SUB_TIMES subtracts the second time. The time1 argument is the address of an unsigned quadword containing this time. The time1 argument must represent a later or equal time or a longer or equal time interval than time2. The time1 argument may be either absolute time or delta time as long as time2 is of the same type. If time1 and time2 are of different types, time1 must be the absolute time. time2 OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference Second time, which LIB$SUB_TIMES subtracts from the first time. The time2 argument is the address of an unsigned quadword containing this time. The time2 argument must represent an earlier or equal time or a shorter or equal time interval than time1. The time2 argument may be either absolute time or delta time as long as time1 is of the same type. If time2 and time1 are of different types, time2 must be the delta time. resultant-time OpenVMS usage:date_time type: quadword (unsigned) access: write only mechanism: by reference The result of subtracting time2 from time1. 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. If both time1 and time2 are absolute times, then resultant-time is a delta time. If time1 is an absolute time and time2 is a delta time, then resultant-time is an absolute time. 3 LIB$SYS_ASCTIM The Invoke $ASCTIM to Convert Binary Time to ASCII String routine calls the system service $ASCTIM to convert a binary date and time value, returning the ASCII string using the semantics of the caller's string. Format LIB$SYS_ASCTIM [resultant-length] ,time-string [,user-time] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of bytes written into time-string, not counting padding in the case of a fixed-length string. The resultant-length argument contains the address of an unsigned word integer that is this number. If the input string is truncated to the size specified in the time-string descriptor, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of time-string. time-string OpenVMS usage:time_name type: character string access: write only mechanism: by descriptor Destination string into which LIB$SYS_ASCTIM writes the ASCII time string. The time-string argument contains the address of a descriptor pointing to the destination string. user-time OpenVMS usage:date_time type: quadword (unsigned) access: read only mechanism: by reference Value that LIB$SYS_ASCTIM converts to ASCII string form. The user-time argument contains the address of a signed quadword integer that is this value. If 0 or no address is specified, the current system date and time are returned. A positive value represents an absolute time. A negative value represents a delta time. Delta times must be less than 10,000 days. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Conversion indicator specifying which date and time fields LIB$SYS_ASCTIM should return. The flags argument is the address of an unsigned bit mask that contains this conversion indicator. A value of 1 causes only the hour, minute, second, and hundredths of a second to be returned, depending on the length of the buffer. A value of 0 (the default) causes the full date and time to be returned, depending on the length of the buffer. The results of specifying some possible combinations for the values of the flags and time-string arguments are shown below: Time- Time String Flags Value Length Value Information Returned Absolute 23 0 Date and time Absolute 12 0 Date Absolute 11 1 Time Delta 16 0 Days and time Delta 11 1 Time The flags argument is passed to LIB$SYS_ASCTIM by reference and is changed to value for use by $ASCTIM. 3 LIB$SYS_FAO The Invoke $FAO System Service to Format Output routine calls the $FAO system service, returning a string in the semantics you provide. If called with other than a fixed-length string for output, the length of the resultant string is limited to 256 bytes and truncation occurs. Format LIB$SYS_FAO character-string, [resultant-length] ,resultant-string [,directive-argument ,...] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments character-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor ASCII control string, consisting of the fixed text of the output string and FAO directives. The character-string argument contains the address of a descriptor pointing to this control string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the output string. The resultant-length argument contains the address of an unsigned word integer that is this length. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Fully formatted output string returned by LIB$SYS_FAO. The resultant-string argument contains the address of a descriptor pointing to this output string. directive-argument OpenVMS usage:varying_arg type: unspecified access: read only mechanism: unspecified Directive argument contained in longwords. Depending on the directive, a directive-argument argument can be a value to be converted, the address of the string to be inserted, or a length or argument count. The passing mechanism for each of these arguments should be the one expected by the $FAO system service. 3 LIB$SYS_FAOL The Invoke $FAOL System Service to Format Output routine calls the $FAOL system service, returning the string in the semantics you provide. If called with other than a fixed-length string for output, the length of the resultant string is limited to 256 bytes and truncation occurs. Format LIB$SYS_FAOL character-string [,resultant-length] ,resultant-string ,directive-argument-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments character-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor ASCII control string, consisting of the fixed text of the output string and FAO directives. The character-string argument contains the address of a descriptor pointing to this control string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the output string. The resultant-length argument contains the address of an unsigned word integer that is this length. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Fully formatted output string returned by LIB$SYS_FAOL. The resultant-string argument contains the address of a descriptor pointing to this output string. directive-argument-address OpenVMS usage:address type: longword (unsigned) access: read only mechanism: unspecified Directive arguments. The directive-argument-address arguments are contained in an array of unsigned longword directive arguments. Depending on the directive, a directive-argument-address argument can be a value to be converted, the address of the string to be inserted, or a length or argument count. The passing mechanism for each of these arguments should be the one expected by the $FAOL system service. 3 LIB$SYS_FAOL_64 (Alpha and I64 only.) The Invoke $FAOL_64 System Service to Format Output routine calls the $FAOL_64 system service, returning the string in the semantics you provide. If called with other than a fixed-length string for output, the length of the resultant string is limited to 256 bytes and truncation occurs. Format LIB$SYS_FAOL_64 character-string [,resultant-length] ,resultant-string ,directive-argument-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments character-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor ASCII control string, consisting of the fixed text of the output string and FAO directives. The character-string argument contains the address of a descriptor pointing to this control string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the output string. The resultant-length argument contains the address of an unsigned word integer that is this length. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Fully formatted output string returned by LIB$SYS_FAOL_64. The resultant-string argument contains the address of a descriptor pointing to this output string. directive-argument-address OpenVMS usage:address type: quadword (unsigned) access: read only mechanism: unspecified Directive arguments. The directive-argument-address arguments are contained in an array of unsigned quadword directive arguments. Depending on the directive, a directive-argument-address argument can be a value to be converted, the address of the string to be inserted, or a length or argument count. The passing mechanism for each of these arguments should be the one expected by the $FAOL_64 system service. 3 LIB$SYS_GETMSG The Invoke $GETMSG System Service to Get Message Text routine calls the system service $GETMSG and returns a message string into destination-string using the semantics of the caller's string. Format LIB$SYS_GETMSG message-id [,message-length] ,destination-string [,flags] [,unsigned-resultant-array] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments message-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Message identification to be retrieved by LIB$SYS_GETMSG. The message-id argument contains the address of an unsigned longword integer that is this message identification. message-length OpenVMS usage:word_unsigned type: word integer (unsigned) access: write only mechanism: by reference Number of characters written into destination-string, not counting padding in the case of a fixed-length string. The message-length argument contains the address of an unsigned word integer that is this number. If the input string is truncated to the size specified in the destination-string descriptor, message-length is set to this size. Therefore, message-length can always be used by the calling program to access a valid substring of destination-string. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string. The destination-string argument contains the address of a descriptor pointing to this destination string. LIB$SYS_GETMSG writes the message that has been returned by $GETMSG into destination-string. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Four flag bits for message content. The flags argument is the address of an unsigned longword that contains these flag bits. The default value is a longword with bits 0 through 3 set to 1. The flags argument is passed to LIB$SYS_GETMSG by reference and changed to value for use by $GETMSG. The following table lists the bit numbers, their values, and corresponding descriptions: Bit Value Description 0 1 Include text of message. 0 Do not include text of message. 1 1 Include message identifier. 0 Do not include message identifier. 2 1 Include severity indicator. 0 Do not include severity indicator. 3 1 Include facility name. 0 Do not include facility name. unsigned-resultant-array OpenVMS usage:unspecified type: unspecified access: write only mechanism: by reference, array reference A 4-byte array to receive message-specific information. The unsigned-resultant-array argument contains the address of this array. The contents of this 4-byte array are as follows: Byte Contents 0 Reserved 1 Count of FAO arguments 2 User value 3 Reserved 3 LIB$TPARSE The Table-Driven Finite-State Parser routine is a general- purpose, table-driven parser implemented as a finite-state automaton, with extensions that make it suitable for a wide range of applications. It parses a string and returns a message indicating whether or not the input string is valid. LIB$T[ABLE_]PARSE is called with the address of an argument block, the address of a state table, and the address of a keyword table. The input string is specified as part of the argument block. The LIB$ facility supports the following two versions of the Table-Driven Finite-State Parser: LIB$TPARSE Available on VAX systems. LIB$TPARSE is available on Alpha and I64 systems in translated form. In this form, it is applicable to translated VAX images only. LIB$TABLE_PARSE Available on VAX, Alpha, and I64 systems. LIB$TPARSE and LIB$TABLE_PARSE differ mainly in the way they pass arguments to action routines. The term LIB$T[ABLE_]PARSE is used here to describe concepts that apply to both LIB$TPARSE and LIB$TABLE_PARSE. Format LIB$TPARSE/LIB$TABLE_PARSE argument-block ,state-table ,key-table 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments argument-block OpenVMS usage:unspecified type: unspecified access: modify mechanism: by reference LIB$T[ABLE_]PARSE argument block. The argument-block argument contains the address of this argument block. The LIB$T[ABLE_]PARSE argument block contains information about the state of the parse operation. It is a means of communication between LIB$T[ABLE_]PARSE and the user's program. It is passed as an argument to all action routines. You must declare and initialize the argument block. LIB$T[ABLE_]PARSE supports the following argument blocks: o A 32-bit argument block that accommodates longword addresses, values, and input tokens on VAX, Alpha, and I64 systems. On Alpha and I64 systems, this argument block also accommodates a numeric token whose binary representation is less than or equal to 2**64. o A 64-bit argument block that accommodates quadword addresses, values, and input tokens on Alpha and I64 systems. state-table OpenVMS usage:unspecified type: unspecified access: read only mechanism: by reference Starting state in the state table. The state-table argument is the address of this starting state. Usually, the name appearing as the first argument of the $INIT_STATE macro is used. You must define the state table for your parser. LIB$T[ABLE_]PARSE provides macros in the MACRO and BLISS languages for this purpose. key-table OpenVMS usage:unspecified type: unspecified access: read only mechanism: by reference Keyword table. The key-table argument is the address of this keyword table. This name must be the same as that which appears as the second argument of the $INIT_STATE macro. You must only assign a name to the keyword table. The LIB$T[ABLE_]PARSE macros allocate and define the table. 3 LIB$TABLE_PARSE The Table-Driven Finite-State Parser routine is a general- purpose, table-driven parser implemented as a finite-state automaton, with extensions that make it suitable for a wide range of applications. It parses a string and returns a message indicating whether or not the input string is valid. LIB$T[ABLE_]PARSE is called with the address of an argument block, the address of a state table, and the address of a keyword table. The input string is specified as part of the argument block. The LIB$ facility supports the following two versions of the Table-Driven Finite-State Parser: LIB$TPARSE Available on VAX systems. LIB$TPARSE is available on Alpha and I64 systems in translated form. In this form, it is applicable to translated VAX images only. LIB$TABLE_PARSE Available on VAX, Alpha, and I64 systems. LIB$TPARSE and LIB$TABLE_PARSE differ mainly in the way they pass arguments to action routines. The term LIB$T[ABLE_]PARSE is used here to describe concepts that apply to both LIB$TPARSE and LIB$TABLE_PARSE. Format LIB$TPARSE/LIB$TABLE_PARSE argument-block ,state-table ,key-table 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments argument-block OpenVMS usage:unspecified type: unspecified access: modify mechanism: by reference LIB$T[ABLE_]PARSE argument block. The argument-block argument contains the address of this argument block. The LIB$T[ABLE_]PARSE argument block contains information about the state of the parse operation. It is a means of communication between LIB$T[ABLE_]PARSE and the user's program. It is passed as an argument to all action routines. You must declare and initialize the argument block. LIB$T[ABLE_]PARSE supports the following argument blocks: o A 32-bit argument block that accommodates longword addresses, values, and input tokens on VAX, Alpha, and I64 systems. On Alpha and I64 systems, this argument block also accommodates a numeric token whose binary representation is less than or equal to 2**64. o A 64-bit argument block that accommodates quadword addresses, values, and input tokens on Alpha and I64 systems. state-table OpenVMS usage:unspecified type: unspecified access: read only mechanism: by reference Starting state in the state table. The state-table argument is the address of this starting state. Usually, the name appearing as the first argument of the $INIT_STATE macro is used. You must define the state table for your parser. LIB$T[ABLE_]PARSE provides macros in the MACRO and BLISS languages for this purpose. key-table OpenVMS usage:unspecified type: unspecified access: read only mechanism: by reference Keyword table. The key-table argument is the address of this keyword table. This name must be the same as that which appears as the second argument of the $INIT_STATE macro. You must only assign a name to the keyword table. The LIB$T[ABLE_]PARSE macros allocate and define the table. 3 LIB$TRAVERSE_TREE The Traverse a Balanced Binary Tree routine calls an action routine for each node in a binary tree. Format LIB$TRAVERSE_TREE treehead ,user-action-procedure [,user-data-address] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments treehead OpenVMS usage:address type: address access: read only mechanism: by reference Tree head of the binary tree. The treehead argument is the address of an unsigned longword that is the tree head in the binary tree traversal. user-action-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied action routine called by LIB$TRAVERSE_TREE for each node in the tree. The user-action-procedure argument must return a success status for LIB$TRAVERSE_TREE to continue traversal. user-data-address OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by reference User data that LIB$TRAVERSE_TREE passes to your action routine. The user-data-address argument contains the address of this user data. This is an optional argument; the default value is 0. 3 LIB$TRAVERSE_TREE_64 (Alpha and I64 only.) The Traverse a Balanced Binary Tree routine calls an action routine for each node in a binary tree. Format LIB$TRAVERSE_TREE_64 treehead ,user-action-procedure [,user-data-address] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments treehead OpenVMS usage:address type: address access: read only mechanism: by reference Tree head of the binary tree. The treehead argument is the address of an unsigned quadword that is the tree head in the binary tree traversal. user-action-procedure OpenVMS usage:procedure type: procedure value access: function call (before return) mechanism: by value User-supplied action routine called by LIB$TRAVERSE_TREE_64 for each node in the tree. The user-action-procedure argument must return a success status for LIB$TRAVERSE_TREE_64 to continue traversal. user-data-address OpenVMS usage:user_arg type: quadword (unsigned) access: read only mechanism: by reference User data that LIB$TRAVERSE_TREE_64 passes to your action routine. The user-data-address argument contains the address of this user data. This is an optional argument; the default value is 0. 3 LIB$TRA_ASC_EBC The Translate ASCII to EBCDIC routine translates an ASCII string to an EBCDIC string. Format LIB$TRA_ASC_EBC source-string ,byte-integer-dest-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string (ASCII) to be translated by LIB$TRA_ASC_EBC. The source-string argument contains the address of a descriptor pointing to this source string. byte-integer-dest-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string (EBCDIC). The byte-integer-dest-string argument contains the address of a descriptor pointing to this destination string. 3 LIB$TRA_EBC_ASC The Translate EBCDIC to ASCII routine translates an EBCDIC string to an ASCII string. Format LIB$TRA_EBC_ASC byte-integer-source-string ,destination-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: read only mechanism: by value 4 Arguments byte-integer-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The byte-integer-source-string argument contains the address of a descriptor pointing to this source string. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string (ASCII). The destination-string argument contains the address of the descriptor of this destination string. The LIB$TRA_EBC_ASC routine uses the EBCDIC to ASCII translation table, LIB$AB_EBC_ASC. 3 LIB$TRIM_FILESPEC The Fit Long File Specification into Fixed Field routine takes a file specification, such as an OpenVMS RMS resultant name string, and shortens it (if necessary) so that it fits into a field of fixed width. Format LIB$TRIM_FILESPEC old-filespec ,new-filespec [,word-integer-width] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments old-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor File specification to be trimmed. The old-filespec argument contains the address of a descriptor pointing to this file specification string. The file specification should be an RMS resultant name string. new-filespec OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Trimmed file specification. The new-filespec argument contains the address of a descriptor pointing to this trimmed file specification string. LIB$TRIM_FILESPEC writes the trimmed file specification into new-filespec. word-integer-width OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Maximum field width desired. The word-integer-width argument is the address of an unsigned word that contains this maximum field width. If omitted, the current length of new-filespec is used. If new- filespec is not a fixed-length string, you should specify word- integer-width to ensure that the desired width is used. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the trimmed file specification, not including any blank padding or truncated characters. The resultant-length argument is the address of an unsigned word that contains this length. This is an optional argument. 3 LIB$TRIM_FULLNAME The Trim a Full Name to Fit into a Desired Output Field routine trims a full name to fit into a desired output field. The trimming preserves the most significant part of the full name. Format LIB$TRIM_FULLNAME fullname, trimmed-nodename [,output-width] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fullname OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Full name to be trimmed. The fullname argument contains the address of a descriptor pointing to this full name string. The error LIB$_INVARG is returned if fullname contains an invalid full name, points to a null string, or contains more than 1024 characters. The error LIB$_INVSTRDES is returned if fullname is an invalid descriptor. trimmed-nodename OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Trimmed node name. The trimmed-nodename argument contains the address of a descriptor pointing to the trimmed node-name string. LIB$TRIM_FULLNAME writes the trimmed node name into the buffer pointed to by trimmed-nodename. The error LIB$_INVSTRDES is returned if trimmed-nodename is an invalid descriptor. The length field of the trimmed-nodename descriptor is not updated unless trimmed-nodename is a dynamic descriptor with a length less than the resultant trimmed node name. Refer to the OpenVMS RTL String Manipulation (STR$) Manual for dynamic string descriptor usage. The trimmed-nodename argument contains an unusable result when LIB$TRIM_FULLNAME returns in error. output-width OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Field width desired for the trimmed node name. The output-width argument is the address of an unsigned word that contains this field width in bytes. If output-width is omitted, the current length of trimmed- nodename is used. If trimmed-nodename is not a fixed-length string, specify output-width to ensure that the desired width is used. If the lengths of both trimmed-nodename and output-width are specified, the length in output-width is used. In this case, if the current length of trimmed-nodename is smaller than the length of output-width, the output trimmed node name is truncated at the end, and the alternate successful status LIB$_STRTRU is returned. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the trimmed 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$TRIM_FULLNAME returns in error. 3 LIB$UNLOCK_IMAGE_(Alpha_and_I64_Only) Unlocks the specified image in the process's working set. Format LIB$UNLOCK_IMAGE address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments address OpenVMS usage:address type: quadword access: read only mechanism: by value Address of a byte within the image to be unlocked in the working set. If the address argument is 0, the current image (which contains the call to LIB$UNLOCK_IMAGE) is unlocked in the working set. 3 LIB$VERIFY_VM_ZONE The Verify a Zone routine performs verification of a 32-bit zone. Format LIB$VERIFY_VM_ZONE zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument zone-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Zone identifier of the zone to be verified. The zone-id argument is the address of an unsigned longword that contains this zone identifier. A value of 0 indicates the 32-bit default zone. 3 LIB$VERIFY_VM_ZONE_64 (Alpha and I64 only.) The Verify a Zone routine performs verification of a 64-bit zone. Format LIB$VERIFY_VM_ZONE_64 zone-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument zone-id OpenVMS usage:identifier type: quadword (unsigned) access: read only mechanism: by reference Zone identifier of the zone to be verified. The zone-id argument is the address of an unsigned quadword that contains this zone identifier. A value of 0 indicates the 64-bit default zone. 3 LIB$WAIT The Wait a Specified Period of Time routine places the current process into hibernation for the number of seconds specified in its argument. Format LIB$WAIT seconds [,flags] [,float-type] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments seconds OpenVMS usage:floating_point type: F_floating access: read only mechanism: by reference The number of seconds to wait. The seconds argument contains the address of an F-floating number that is this number. The value is rounded to the nearest hundredth-second before use. Seconds must be between 0.0 and 100,000.0. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Control flags. The flags argument is the address of a longword integer that contains the control flags. The following flag is defined: Bit Value Description 0 LIB$K_NOWAKE LIB$WAIT will not wake in the case of an interrupt. This is an optional argument. If omitted, the default is 0, and LIB$WAIT will wake in the case of an interrupt. float-type OpenVMS usage:longword-unsigned type: longword (unsigned) access: read only mechanism: by reference Float type. The float-type argument is the address of a longword integer that determines the floating-point type of the seconds argument. Use one of the following symbols: Symbol Value Floating-Point Type LIB$K_VAX_F 0 F_floating LIB$K_VAX_D 1 D_floating LIB$K_VAX_G 2 G_floating LIB$K_VAX_H 3 H_floating LIB$K_IEEE_S 4 IEEE_S_floating LIB$K_IEEE_T 5 IEEE_T_floating This is an optional argument. If omitted, the default is F_ floating. F_floating is the required float-type when LIB$WAIT is called from a module written in a language that prototypes functions. 2 OTS$ 3 OTS$CALL_PROC (Alpha and I64 only.) The Call Special Procedure routine performs a call to a procedure that may be either in native code or in a translated image. Format OTS$CALL_PROC target-func-value ,target-sig-info ,standard-args ,... 4 Returns None. 4 Arguments target-func-value OpenVMS usage:function value type: quadword address access: read only mechanism: by value in register R23 (Alpha). by value in register R17 (I64). Function value for the procedure to be called. target-sig-info OpenVMS usage:TIE signature information type: TIE signature block access: read only mechanism: by reference in register R24 (Alpha). by value in register R17 (I64). Signature information is used to transform the standard arguments into the form required by a translated image (if needed). The representation of signature information is described in the OpenVMS Calling Standard. standard-args type: access: mechanism: 0 Zero or more arguments to be passed to the called routine, passed using standard conventions (including the AI register). 4 Description When translated code support is requested, the compiled code must call the special service routine, OTS$CALL_PROC. The actual parameters to the target function are passed to OTS$CALL_PROC as though the target routine is native code that is being invoked directly. OTS$CALL_PROC first determines whether the target routine is part of a translated image. If the target is in native code, then OTS$CALL_PROC completes the call in a way that makes its mediation transparent (that is, control need not pass back through it for the return). The native parameters are used without modification. If the target is in translated code, then OTS$CALL_PROC passes control to the Translated Image Environment (TIE). 4 Condition_Values_Returned None. 3 OTS$CNVOUT The Convert Floating to Character String routines convert a D-floating, G-floating, H-floating, IEEE S-floating, or IEEE T-floating number to a character string in the Fortran E format. Format OTS$CNVOUT D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction OTS$CNVOUT_G D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction OTS$CNVOUT_H D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction (VAX only) OTS$CNVOUT_S D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction (VAX only) OTS$CNVOUT_T D-G-H-S-or-T-float-pt-input-val ,fixed-length-resultant-string ,digits-in-fraction (VAX only) 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments D-G-H-S-or-T-float-pt-input-val OpenVMS usage:floating_point type: D_floating, G_floating, H_floating, IEEE S_floating, IEEE T_floating access: read only mechanism: by reference Value that OTS$CNVOUT converts to a character string. For OTS$CNVOUT, the D-G-H-S-or-T-float-pt-input-val argument is the address of a D-floating number containing the value. For OTS$CNVOUT_G, the D-G-H-S-or-T-float-pt-input-val argument is the address of a G-floating number containing the value. For OTS$CNVOUT_S, the D-G-H-S-or-T-float-pt-input-val argument is the address of an IEEE S-floating number containing the value. For OTS$CNVOUT_T, the D-G-H-S-or-T-float-pt-input-val argument is the address of an IEEE T-floating number containing the value. fixed-length-resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor, fixed length Output string into which OTS$CNVOUT writes the character string result of the conversion. The fixed-length-resultant-string argument is the address of a descriptor pointing to the output string. digits-in-fraction OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Number of digits in the fractional portion of the result. The digits-in-fraction argument is an unsigned longword containing the number of digits to be written to the fractional portion of the result. 3 OTS$CVT_L_TB The Convert an Unsigned Integer to Binary Text routine converts an unsigned integer value of arbitrary length to binary representation in an ASCII text string. By default, a longword is converted. Format OTS$CVT_L_TB varying-input-value,fixed-length-resultant-string [,number-of-digits] [,input-value-size] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments varying-input-value OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by reference Unsigned byte, word, or longword that OTS$CVT_L_TB converts to an unsigned decimal representation in an ASCII text string. (The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword.) The varying- input-value argument is the address of the unsigned integer. fixed-length-resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor, fixed length ASCII text string that OTS$CVT_L_TB creates when it converts the integer value. The fixed-length-resultant-string argument is the address of a descriptor pointing to this ASCII text string. The string is assumed to be of fixed length (CLASS_S descriptor). number-of-digits OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Minimum number of digits in the binary representation to be generated. The number-of-digits argument is a signed longword containing this minimum number. If the minimum number of digits is omitted, the default is 1. If the actual number of significant digits is less than the minimum number of digits, leading zeros are produced. If the minimum number of digits is zero and the value of the integer to be converted is also zero, OTS$CVT_L_TB creates a blank string. input-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Size of the integer to be converted, in bytes. The input-value- size argument is a signed longword containing the byte size. This is an optional argument. If the size is omitted, the default is 4 (longword). 3 OTS$CVT_L_TI The Convert Signed Integer to Decimal Text routine converts a signed integer to its decimal representation in an ASCII text string. This routine supports Fortran Iw and Iw.m output and BASIC output conversion. Format OTS$CVT_L_TI varying-input-value ,fixed-length-resultant-string [,number-of-digits] [,input-value-size] [,flags-value] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments varying-input-value OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by reference, fixed length A signed integer that OTS$CVT_L_TI converts to a signed decimal representation in an ASCII text string. The varying-input-value argument is the address of the signed integer. On VAX systems, the integer can be a signed byte, word, or longword. The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword. On Alpha and I64 systems, the integer can be a signed byte, word, longword, or quadword. The value of the input-value-size argument determines whether varying-input-value is a byte, word, longword, or quadword. fixed-length-resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Decimal ASCII text string that OTS$CVT_L_TI creates when it converts the signed integer. The fixed-length-resultant-string argument is the address of a CLASS_S descriptor pointing to this text string. The string is assumed to be of fixed length. number-of-digits OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Minimum number of digits to be generated when OTS$CVT_L_TI converts the signed integer to a decimal ASCII text string. The number-of-digits argument is a signed longword containing this number. If the minimum number of digits is omitted, the default value is 1. If the actual number of significant digits is smaller, OTS$CVT_L_TI inserts leading zeros into the output string. If number-of-digits is zero and varying-input-value is zero, OTS$CVT_L_TI writes a blank string to the output string. input-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Size of the integer to be converted, in bytes. The input-value- size argument is a signed longword containing this value size. If the size is omitted, the default is 4 (longword). On VAX systems, the value size must be 1, 2, or 4. If value size is 1 or 2, the value is sign-extended to a longword before conversion. On Alpha and I64 systems, the value size must be 1, 2, 4, or 8. If the value is 1, 2, or 4, the value is sign-extended to a quadword before conversion. flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value Caller-supplied flags that you can use if you want OTS$CVT_L_TI to insert a plus sign before the converted number. The flags- value argument is an unsigned longword containing the flags. The caller flags are described in the following table: Bit Action if Set Action if Clear 0 Insert a plus sign Omit the plus sign. (+) before the first nonblank character in the output string. If flags-value is omitted, all bits are clear and the plus sign is not inserted. 3 OTS$CVT_L_TL The Convert Integer to Logical Text routine converts an integer to an ASCII text string representation using Fortran L (logical) format. Format OTS$CVT_L_TL longword-integer-value ,fixed-length-resultant-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments longword-integer-value OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Value that OTS$CVT_L_TL converts to an ASCII text string. The longword-integer-value argument is the address of a signed longword containing this integer value. fixed-length-resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor, fixed length Output string that OTS$CVT_L_TL creates when it converts the integer value to an ASCII text string. The fixed-length- resultant-string argument is the address of a descriptor pointing to this ASCII text string. The output string is assumed to be of fixed length (CLASS_S descriptor). If bit 0 of longword-integer-value is set, OTS$CVT_L_TL stores the character T in the rightmost character of fixed-length- resultant-string. If bit 0 is clear, it stores the character F. In either case, it fills the remaining characters of fixed- length-resultant-string with blanks. 3 OTS$CVT_L_TO The Convert Unsigned Integer to Octal Text routine converts an unsigned integer to an octal ASCII text string. OTS$CVT_L_TO supports Fortran Ow and Ow.m output conversion formats. Format OTS$CVT_L_TO varying-input-value ,fixed-length-resultant-string [,number-of-digits] [,input-value-size] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments varying-input-value OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by reference Unsigned byte, word, or longword that OTS$CVT_L_TO converts to an unsigned decimal representation in an ASCII text string. (The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword.) The varying- input-value argument is the address of the unsigned integer. fixed-length-resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor, fixed length Output string that OTS$CVT_L_TO creates when it converts the integer value to an octal ASCII text string. The fixed-length- resultant-string argument is the address of a descriptor pointing to the octal ASCII text string. The string is assumed to be of fixed length (CLASS_S descriptor). number-of-digits OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Minimum number of digits that OTS$CVT_L_TO generates when it converts the integer value to an octal ASCII text string. The number-of-digits argument is a signed longword containing the minimum number of digits. If it is omitted, the default is 1. If the actual number of significant digits in the octal ASCII text string is less than the minimum number of digits, OTS$CVT_L_TO inserts leading zeros into the output string. If number-of-digits is 0 and varying-input-value is 0, OTS$CVT_L_TO writes a blank string to the output string. input-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Size of the integer to be converted, in bytes. The input-value- size argument is a signed longword containing the number of bytes in the integer to be converted by OTS$CVT_L_TO. If it is omitted, the default is 4 (longword). 3 OTS$CVT_L_TU The Convert Unsigned Integer to Decimal Text routine converts an unsigned integer value to its unsigned decimal representation in an ASCII text string. Format OTS$CVT_L_TU varying-input-value ,fixed-length-resultant-string [,number-of-digits] [,input-value-size] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments varying-input-value OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by reference An unsigned integer that OTS$CVT_L_TU converts to an unsigned decimal representation in an ASCII text string. The varying- input-value argument is the address of the unsigned integer. On VAX systems, the integer can be an unsigned byte, word, or longword. (The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword.) On Alpha and I64 systems, the integer can be an unsigned byte, word, longword, or quadword. (The value of the input-value-size argument determines whether varying-input-value is a byte, word, longword, or quadword.) fixed-length-resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor, fixed length Output string that OTS$CVT_L_TU creates when it converts the integer value to unsigned decimal representation in an ASCII text string. The fixed-length-resultant-string argument is the address of a descriptor pointing to this ASCII text string. number-of-digits OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Minimum number of digits in the ASCII text string that OTS$CVT_ L_TU creates. The number-of-digits argument is a signed longword containing the minimum number. If the minimum number of digits is omitted, the default is 1. If the actual number of significant digits in the output string created is less than the minimum number, OTS$CVT_L_TU inserts leading zeros into the output string. If the minimum number of digits is zero and the integer value to be converted is also zero, OTS$CVT_L_TU writes a blank string to the output string. input-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Size of the integer to be converted, in bytes. The input-value- size argument is a signed longword containing this value size. If the size is omitted, the default is 4 (longword). On VAX systems, the value size must be 1, 2, or 4. On Alpha and I64 systems, the value size must be 1, 2, 4, or 8. 3 OTS$CVT_L_TZ The Convert Integer to Hexadecimal Text routine converts an unsigned integer to a hexadecimal ASCII text string. OTS$CVT_ L_TZ supports Fortran Zw and Zw.m output conversion formats. Format OTS$CVT_L_TZ varying-input-value ,fixed-length-resultant-string [,number-of-digits] [,input-value-size] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments varying-input-value OpenVMS usage:varying_arg type: unspecified access: read only mechanism: by reference Unsigned byte, word, or longword that OTS$CVT_L_TZ converts to an unsigned decimal representation in an ASCII text string. (The value of the input-value-size argument determines whether varying-input-value is a byte, word, or longword.) The varying- input-value argument is the address of the unsigned integer. fixed-length-resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor, fixed length Output string that OTS$CVT_L_TZ creates when it converts the integer value to a hexadecimal ASCII text string. The fixed- length-resultant-string argument is the address of a descriptor pointing to this ASCII text string. The string is assumed to be of fixed length (CLASS_S descriptor). number-of-digits OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Minimum number of digits in the ASCII text string that OTS$CVT_ L_TZ creates when it converts the integer. The number-of-digits argument is a signed longword containing this minimum number. If it is omitted, the default is 1. If the actual number of significant digits in the text string that OTS$CVT_L_TZ creates is less than this minimum number, OTS$CVT_L_TZ inserts leading zeros in the output string. If the minimum number of digits is zero and the integer value to be converted is also zero, OTS$CVT_ L_TZ writes a blank string to the output string. input-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Size of the integer that OTS$CVT_L_TZ converts, in bytes. The input-value-size argument is a signed longword containing the value size. If the size is omitted, the default is 4 (longword). 3 OTS$CVT_T_x The Convert Numeric Text to D-, F-, G-, H-, IEEE S-, or IEEE T- Floating routines convert an ASCII text string representation of a numeric value to a D-floating, F-floating, G-floating, H- floating, IEEE S-floating, or IEEE T-floating value. Format OTS$CVT_T_D fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits] OTS$CVT_T_F fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits] OTS$CVT_T_G fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits] OTS$CVT_T_H fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits] OTS$CVT_T_S fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits] OTS$CVT_T_T fixed-or-dynamic-input-string ,floating-point-value [,digits-in-fraction] [,scale-factor] [,flags-value] [,extension-bits] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fixed-or-dynamic-input-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor, fixed-length or dynamic string Input string containing an ASCII text string representation of a numeric value that OTS$CVT_T_x converts to a D-floating, F- floating, G-floating, H-floating, IEEE S-floating, or IEEE T- floating value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. The syntax of a valid input string is as follows: [blanks][+ or -][digits][.][digits][+ or -][digits] or [blanks][+ or -][digits][.][digits][ X ][digits] where X = {E e D d Q q}[blanks][+ or -] E, e, D, d, Q, and q are the possible exponent letters. They are semantically equivalent. Other elements in the preceding syntax are defined as follows: Term Description blanks One or more blanks digits One or more decimal digits floating-point-value OpenVMS usage:floating_point type: D_floating, F_floating, G_floating, H_floating, IEEE S_floating, IEEE T_floating access: write only mechanism: by reference Floating-point value that OTS$CVT_T_x creates when it converts the input string. The floating-point-value argument is the address of the floating-point value. The data type of floating- point-value depends on the called routine as shown in the following table: Routine floating-point-value Data Type OTS$CVT_T_D D-floating OTS$CVT_T_F F-floating OTS$CVT_T_G G-floating OTS$CVT_T_H H-floating OTS$CVT_T_S IEEE S-floating OTS$CVT_T_T IEEE T-floating digits-in-fraction OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Number of digits in the fraction if no decimal point is included in the input string. The digits-in-fraction argument contains the number of digits. If the number of digits is omitted, the default is zero. scale-factor OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Scale factor. The scale-factor argument contains the value of the scale factor. If bit 6 of the flags-value argument is clear, the resultant value is divided by 10**scale-factor unless the exponent is present. If bit 6 of flags-value is set, the scale factor is always applied. If the scale factor is omitted, the default is zero. flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value User-supplied flags. The flags-value argument contains the user- supplied flags described in the following table: Bit Action if Set Action if Clear 0 Ignore blanks. Interpret blanks as zeros. 1 Allow only E or e Allow E, e, D, d, Q and q exponents. exponents. (This (This is consistent with BASIC is consistent with semantics.) Fortran semantics.) 2 Interpret an Do not interpret an underflow as an underflow as an error. error. 3 Truncate the value. Round the value. 4 Ignore tabs. Interpret tabs as invalid characters. 5 An exponent must The exponent letter can be omitted. begin with a valid exponent letter. 6 Always apply the Apply the scale factor only if there scale factor. is no exponent present in the string. If you omit the flags-value argument, OTS$CVT_T_x defaults all flags to clear. extension-bits (D-, F-floating, IEEE S-floating) OpenVMS usage:byte_unsigned type: byte (unsigned) access: write only mechanism: by reference extension-bits (G-, H-floating, IEEE T-floating) OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Extra precision bits. The extension-bits argument is the address of a word containing the extra precision bits. If extension- bits is present, floating-point-value is not rounded, and the first n bits after truncation are returned left-justified in this argument, as follows: Number of Bits Routine Returned Data Type OTS$CVT_T_D 8 Byte (unsigned) OTS$CVT_T_F 8 Byte (unsigned) OTS$CVT_T_G 11 Word (unsigned) OTS$CVT_T_H 15 Word (unsigned) OTS$CVT_T_S 8 Byte (unsigned) OTS$CVT_T_T 11 Word (unsigned) A value represented by extension bits is suitable for use as the extension operand in an EMOD instruction. The extra precision bits returned for H-floating may not be precise because OTS$CVT_T_H carries its calculations to only 128 bits. However the error should be small. 3 OTS$CVT_TB_L The Convert Binary Text to Unsigned Integer routine converts an ASCII text string representation of an unsigned binary value to an unsigned integer value. The integer value can be of arbitrary length but is typically a byte, word, longword, or quadword. The default size of the result is a longword. Format OTS$CVT_TB_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] [,flags-value] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fixed-or-dynamic-input-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Input string containing the string representation of an unsigned binary value that OTS$CVT_TB_L converts to an unsigned integer value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. The valid input characters are blanks and the digits 0 and 1. No sign is permitted. varying-output-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Unsigned integer of specified size that OTS$CVT_TB_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the integer. The value of the output- value-size argument determines the size in bytes of the output value. output-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Arbitrary number of bytes to be occupied by the unsigned integer output value. The output-value-size argument contains a value that equals the size in bytes of the output value. If the value of output-value-size is zero or a negative number, OTS$CVT_TB_L returns an input conversion error. If you omit the output-value- size argument, the default is 4 (longword). flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value User-supplied flag that OTS$CVT_TB_L uses to determine how to interpret blanks within the input string. The flags-value argument contains this user-supplied flag. OTS$CVT_TB_L defines the flag as follows: Bit Action if Set Action if Clear 0 Ignore blanks. Interpret blanks as zeros. If you omit the flags-value argument, OTS$CVT_TB_L defaults all flags to clear. 3 OTS$CVT_TI_L The Convert Signed Integer Text to Integer routine converts an ASCII text string representation of a signed decimal number to a signed integer value. The default size of the result is a longword. Format OTS$CVT_TI_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] [,flags-value] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fixed-or-dynamic-input-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor, fixed-length or dynamic string Input ASCII text string that OTS$CVT_TI_L converts to a signed integer. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. [+ or -] OTS$CVT_TI_L always ignores leading blanks. varying-output-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Signed integer that OTS$CVT_TI_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the signed integer. The value of the output-value-size argument determines the size of varying-output-value. output-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Number of bytes to be occupied by the value created when OTS$CVT_ TI_L converts the ASCII text string to an integer value. The output-value-size argument contains the number of bytes in varying-output-value. On VAX systems, valid values for the output-value-size argument are 1, 2, and 4. The value determines whether the integer value that OTS$CVT_TI_L creates is a byte, word, or longword. On Alpha and I64 systems, valid values for the output-value- size argument are 1, 2, 4, and 8. The value determines whether the integer value that OTS$CVT_TI_L creates is a byte, word, longword, or quadword. For VAX and Alpha systems, if you specify a 0 (zero) or omit the output-value-size argument, the size of the output value defaults to 4 (longword). If you specify any other value, OTS$CVT_TI_L returns an input conversion error. flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value User-supplied flags that OTS$CVT_TI_L uses to determine how blanks and tabs are interpreted. The flags-value argument is an unsigned longword containing the value of the flags. Bit Action if Set Action if Clear 0 Ignore all Ignore leading blanks but interpret blanks blanks. after the first legal character as zeros. 4 Ignore tabs. Interpret tabs as invalid characters. If you omit the flags-value argument, OTS$CVT_TI_L defaults all flags to clear. 3 OTS$CVT_TL_L The Convert Logical Text to Integer routine converts an ASCII text string representation of a FORTRAN-77 L format to a signed integer. Format OTS$CVT_TL_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fixed-or-dynamic-input-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor, fixed-length or dynamic string Input string containing an ASCII text representation of a FORTRAN-77 L format that OTS$CVT_TL_L converts to a signed integer value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. Common ASCII text representations of a FORTRAN-77 logical are .TRUE., .FALSE., T, t, F, and f. In practice, an OTS$CVT_TL_L input string is valid if it adheres to the following syntax: or [][.]{T t F f}[] One of the letters T, t, F, or f is required. Other elements in the preceding syntax are defined as follows: Term Description blanks One or more blanks characters One or more of any character varying-output-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Signed integer that OTS$CVT_TL_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the signed integer. The value of the output-value-size argument determines the size in bytes of the signed integer. OTS$CVT_TL_L returns -1 as the contents of the varying-output- value argument if the character denoted by "letter" is T or t. Otherwise, OTS$CVT_TL_L sets varying-output-value to zero. output-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Number of bytes to be occupied by the signed integer created when OTS$CVT_TL_L converts the ASCII text string to an integer value. The output-value-size argument contains a value that equals the size in bytes of the output value. If output-value- size contains a zero or a negative number, OTS$CVT_TL_L returns an input conversion error. On VAX systems, valid values for the output-value-size argument are 1, 2, and 4. The value determines whether the integer value that OTS$CVT_TL_L creates is a byte, word, or longword. On Alpha and I64 systems, valid values for the output-value- size argument are 1, 2, 4, and 8. This value determines whether the integer value that OTS$CVT_TL_L creates is a byte, word, longword, or quadword. For VAX, Alpha, and I64 systems, if you omit the output-value- size argument, the default is 4 (longword). 3 OTS$CVT_TO_L The Convert Octal Text to Unsigned Integer routine converts an ASCII text string representation of an unsigned octal value to an unsigned integer. The integer value can be of arbitrary length but is typically a byte, word, longword, or quadword. The default size of the result is a longword. Format OTS$CVT_TO_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] [,flags-value] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fixed-or-dynamic-input-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor, fixed-length or dynamic string Input string containing the string representation of an unsigned octal value that OTS$CVT_TO_L converts to an unsigned integer. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. The valid input characters are blanks and the digits 0 through 7. No sign is permitted. varying-output-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Unsigned integer of specified size that OTS$CVT_TO_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the unsigned integer. The value of the output-value-size argument determines the size in bytes of the output value. output-value-size OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by value Arbitrary number of bytes to be occupied by the unsigned integer output value. The output-value-size argument contains a value that equals the size in bytes of the output value. If the value of output-value-size is zero or a negative number, OTS$CVT_TO_L returns an input conversion error. If you omit the output-value- size argument, the default is 4 (longword). flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value User-supplied flag that OTS$CVT_TO_L uses to determine how to interpret blanks within the input string. The flags-value argument contains the user-supplied flag described in the following table: Bit Action if Set Action if Clear 0 Ignore all Interpret blanks as zeros. blanks. If you omit the flags-value argument, OTS$CVT_TO_L defaults the flag to clear. 3 OTS$CVT_TU_L The Convert Unsigned Decimal Text to Integer routine converts an ASCII text string representation of an unsigned decimal value to an unsigned integer value. By default, the size of the result is a longword. Format OTS$CVT_TU_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] [,flags-value] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fixed-or-dynamic-input-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Input string containing an ASCII text string representation of an unsigned decimal value that OTS$CVT_TU_L converts to an unsigned integer value. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. Valid input characters are the space and the digits 0 through 9. No sign is permitted. varying-output-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Unsigned integer that OTS$CVT_TU_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the unsigned integer. The value of the output-value- size argument determines the size of varying-output-value. output-value-size OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by value Number of bytes occupied by the value created when OTS$CVT_ TU_L converts the input string. The output-value-size argument contains the number of bytes in varying-output-value. On VAX systems, valid values for the output-value-size argument are 1, 2, and 4. The value determines whether the integer value that OTS$CVT_TU_L creates is a byte, word, or longword. On Alpha and I64 systems, valid values for the output-value- size argument are 1, 2, 4, and 8. The value determines whether the integer value that OTS$CVT_TU_L creates is a byte, word, longword, or quadword. For VAX, Alpha, and I64 systems, if you specify a 0 (zero) or omit the output-value-size argument, the size of the output value defaults to 4 (longword). If you specify any other value, OTS$CVT_TU_L returns an input conversion error. flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value User-supplied flags that OTS$CVT_TU_L uses to determine how blanks and tabs are interpreted. The flags-value argument contains the user-supplied flags as described in the following table: Bit Action if Set Action if Clear 0 Ignore all Ignore leading blanks but interpret blanks blanks. after the first legal character as zeros. 4 Ignore tabs. Interpret tabs as invalid characters. If you omit the flags-value argument, OTS$CVT_TU_L defaults all flags to clear. 3 OTS$CVT_TZ_L The Convert Hexadecimal Text to Unsigned Integer routine converts an ASCII text string representation of an unsigned hexadecimal value to an unsigned integer. The integer value can be of arbitrary length but is typically a byte, word, longword, or quadword. The default size of the result is a longword. Format OTS$CVT_TZ_L fixed-or-dynamic-input-string ,varying-output-value [,output-value-size] [,flags-value] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments fixed-or-dynamic-input-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor, fixed-length or dynamic string Input string containing the string representation of an unsigned hexadecimal value that OTS$CVT_TZ_L converts to an unsigned integer. The fixed-or-dynamic-input-string argument is the address of a descriptor pointing to the input string. The valid input characters are blanks, the digits 0 through 7, and the letters A through F. Letters can be uppercase or lowercase. No sign is permitted. varying-output-value OpenVMS usage:varying_arg type: unspecified access: write only mechanism: by reference Unsigned integer of specified size that OTS$CVT_TZ_L creates when it converts the ASCII text string. The varying-output-value argument is the address of the unsigned integer. The value of the output-value-size argument determines the size in bytes of the output value. output-value-size OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Arbitrary number of bytes to be occupied by the unsigned integer output value. The output-value-size argument contains a value that equals the size in bytes of the output value. If the value of output-value-size is zero or a negative number, OTS$CVT_TZ_L returns an input conversion error. If you omit the output-value- size argument, the default is 4 (longword). flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value User-supplied flags that OTS$CVT_TZ_L uses to determine how to interpret blanks within the input string. The flags-value argument contains these user-supplied flags as described in the following table: Bit Action if Set Action if Clear 0 Ignore all Interpret blanks as zeros. blanks. If you omit the flags-value argument, OTS$CVT_TZ_L defaults the flag to clear. 3 OTS$DIVCx The Complex Division routines return a complex result of a division on complex numbers. Format OTS$DIVC complex-dividend ,complex-divisor OTS$DIVCD_R3 complex-dividend ,complex-divisor (VAX only) OTS$DIVCG_R3 complex-dividend ,complex-divisor OTS$DIVCS complex-dividend ,complex-divisor OTS$DIVCT_R3 complex-dividend ,complex-divisor 4 Returns OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex, access: write only mechanism: by value Complex result of complex division. OTS$DIVC returns an F- floating complex number. OTS$DIVCD_R3 returns a D-floating complex number. OTS$DIVCG_R3 returns a G-floating complex number. OST$DIVCS returns an IEEE S-floating complex number. OTS$DIVCT_R3 returns an IEEE T-floating complex number. 4 Arguments complex-dividend OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex access: read only mechanism: by value Complex dividend. The complex-dividend argument contains a floating-point complex value. For OTS$DIVC, complex-dividend is an F-floating complex number. For OTS$DIVCD_R3, complex- dividend is a D-floating complex number. For OTS$DIVCG_R3, complex-dividend is a G-floating complex number. For OTS$DIVCT_ R3, complex-dividend is an IEEE T-floating complex number. complex-divisor OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex access: read only mechanism: by value Complex divisor. The complex-divisor argument contains the value of the divisor. For OTS$DIVC, complex-divisor is an F-floating complex number. For OTS$DIVCD_R3, complex-divisor is a D-floating complex number. For OTS$DIVCG_R3, complex-divisor is a G-floating complex number. For OTS$DIVCS, complex-divisor is an IEEE S- floating complex number. For OTS$DIVCS, complex-dividend is an IEEE S-floating complex number. For OTS$DIVCT_R3, complex-divisor is an IEEE T-floating complex number. 3 OTS$DIV_PK_LONG The Packed Decimal Division with Long Divisor routine divides fixed-point decimal data, which is stored in packed decimal form, when precision and scale requirements for the quotient call for multiple precision division. The divisor must have a precision of 30 or 31 digits. Format OTS$DIV_PK_LONG packed-decimal-dividend ,packed-decimal-divisor ,divisor-precision ,packed-decimal-quotient ,quotient-precision ,precision-data ,scale-data 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments packed-decimal-dividend OpenVMS usage:varying_arg type: packed decimal string access: read only mechanism: by reference Dividend. The packed-decimal-dividend argument is the address of a packed decimal string that contains the shifted dividend. Before being passed as input, the packed-decimal-dividend argument is always multiplied by 10**c, where c is defined as follows: c = 31 - prec(packed-decimal-dividend) Multiplying packed-decimal-dividend by 10**c makes packed- decimal-dividend a 31-digit number. packed-decimal-divisor OpenVMS usage:varying_arg type: packed decimal string access: read only mechanism: by reference Divisor. The packed-decimal-divisor argument is the address of a packed decimal string that contains the divisor. divisor-precision OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Precision of the divisor. The divisor-precision argument is a signed word that contains the precision of the divisor. The high- order bits are filled with zeros. packed-decimal-quotient OpenVMS usage:varying_arg type: packed decimal string access: write only mechanism: by reference Quotient. The packed-decimal-quotient argument is the address of the packed decimal string into which OTS$DIV_PK_LONG writes the quotient. quotient-precision OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Precision of the quotient. The quotient-precision argument is a signed word that contains the precision of the quotient. The high-order bits are filled with zeros. precision-data OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Additional digits of precision required. The precision-data argument is a signed word that contains the value of the additional digits of precision required. OTS$DIV_PK_LONG computes the precision-data argument as follows: precision-data = scale(packed-decimal-quotient) + scale(packed-decimal-divisor) - scale(packed-decimal-dividend) - 31 + prec(packed-decimal-dividend) scale-data OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Scale factor of the decimal point. The scale-data argument is a signed word that contains the scale data. OTS$DIV_PK_LONG defines the scale-data argument as follows: scale-data = 31 - prec(packed-decimal-divisor) 3 OTS$DIV_PK_SHORT The Packed Decimal Division with Short Divisor routine divides fixed-point decimal data when precision and scale requirements for the quotient call for multiple-precision division. Format OTS$DIV_PK_SHORT packed-decimal-dividend ,packed-decimal-divisor ,divisor-precision ,packed-decimal-quotient ,quotient-precision ,precision-data 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments packed-decimal-dividend OpenVMS usage:varying_arg type: packed decimal string access: read only mechanism: by reference Dividend. The packed-decimal-dividend argument is the address of a packed decimal string that contains the shifted dividend. Before being passed as input, the packed-decimal-dividend argument is always multiplied by 10**c, where c is defined as follows: c = 31 - prec(packed-decimal-dividend) Multiplying packed-decimal-dividend by 10**c makes packed- decimal-dividend a 31-digit number. packed-decimal-divisor OpenVMS usage:varying_arg type: packed decimal string access: read only mechanism: by reference Divisor. The packed-decimal-divisor argument is the address of a packed decimal string that contains the divisor. divisor-precision OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Precision of the divisor. The divisor-precision argument is a signed word integer that contains the precision of the divisor; high-order bits are filled with zeros. packed-decimal-quotient OpenVMS usage:varying_arg type: packed decimal string access: write only mechanism: by reference Quotient. The packed-decimal-quotient argument is the address of a packed decimal string into which OTS$DIV_PK_SHORT writes the quotient. quotient-precision OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Precision of the quotient. The quotient-precision argument is a signed word that contains the precision of the quotient; high- order bits are filled with zeros. precision-data OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Additional digits of precision required. The precision-data argument is a signed word that contains the value of the additional digits of precision required. OTS$DIV_PK_SHORT computes the precision-data argument as follows: precision-data = scale(packed-decimal-quotient) + scale(packed-decimal-divisor) - scale(packed-decimal-dividend) - 31 + prec(packed-decimal-dividend) 3 OTS$JUMP_TO_BPV I64 only. The Jump to Bound Procedure Value routine transfers control to a bound procedure. Format OTS$JUMP_TO_BPV bound-func-value ,standard-args ,... 4 Returns None. 4 Arguments bound-func-value OpenVMS usage:quadword address type: address access: read only mechanism: by value in register R1 (GP) Function value for the procedure being called. standard-args type: access: mechanism: 0 Zero or more arguments to be passed to the called routine, passed using standard conventions (including the AI register). 4 Description When a procedure value that refers to a bound procedure descriptor is used to make a call, the routine designated in the OTS_ENTRY field (typically OTS$JUMP_TO_BPV) receives control with the GP register pointing to the bound procedure descriptor (instead of a global offset table). This routine performs the following steps: 1. Load the "real" target entry address into a volatile branch register, for example, B6. 2. Load the dynamic environment value into the appropriate uplevel-addressing register for the target function, for example, OTS$JUMP_TO_BPV uses R9. 3. Load the "real" target GP address into the GP register 4. Transfer control (branch, not call) to the target entry address. Control arrives at the real target procedure address with both the GP and environment register values established appropriately. Support routine OTS$JUMP_TO_BPV is included as a standard library routine. The operation of OTS$JUMP_TO_BPV is logically equivalent to the following code: OTS$JUMP_TO_BPV:: add gp=gp,24 ; Adjust GP to point to entry address ld8 r9=[gp],16 ; Load target entry address mov b6=r9 ld8 r9=[gp],-8 ; Load target environment value ld8 gp=[gp] ; Load target GP br b6 ; Transfer to target Note that there can be multiple OTS$JUMP_TO_BPV-like support routines, corresponding to different target registers where the environment value should be placed. The code that creates the bound function descriptor is also necessarily compiled by the same compiler that compiles the target procedure, thus can correctly select an appropriate support routine. 4 Condition_Values_Returned None. 3 OTS$MOVE3 The Move Data Without Fill routine moves up to 2**31-1 bytes (2,147,483,647 bytes) from a specified source address to a specified destination address. Format OTS$MOVE3 length-value ,source-array ,destination-array 4 Corresponding_JSB_Entry_Point OTS$MOVE3_R5 4 Returns None. 4 Arguments length-value OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Number of bytes of data to move. The length-value argument is a signed longword that contains the number of bytes to move. The value of length-value may range from 0 to 2,147,483,647 bytes. source-array OpenVMS usage:vector_byte_unsigned type: byte (unsigned) access: read only mechanism: by reference, array reference Data to be moved by OTS$MOVE3. The source-array argument contains the address of an unsigned byte array that contains this data. destination-array OpenVMS usage:vector_byte_unsigned type: byte (unsigned) access: write only mechanism: by reference, array reference Address into which source-array will be moved. The destination- array argument is the address of an unsigned byte array into which OTS$MOVE3 writes the source data. 3 OTS$MOVE5 The Move Data with Fill routine moves up to 2**32-1 bytes (2,147,483,647 bytes) from a specified source address to a specified destination address, with separate source and destination lengths, and with fill. Overlap of the source and destination arrays does not affect the result. Format OTS$MOVE5 longword-int-source-length ,source-array ,fill-value ,longword-int-dest-length ,destination-array 4 Corresponding_JSB_Entry_Point OTS$MOVE5_R5 4 Returns None. 4 Arguments longword-int-source-length OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Number of bytes of data to move. The longword-int-source- length argument is a signed longword that contains this number. The value of longword-int-source-length may range from 0 to 2,147,483,647. source-array OpenVMS usage:vector_byte_unsigned type: byte (unsigned) access: read only mechanism: by reference, array reference Data to be moved by OTS$MOVE5. The source-array argument contains the address of an unsigned byte array that contains this data. fill-value OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by value Character used to pad the source data if longword-int-source- length is less than longword-int-dest-length. The fill-value argument contains the address of an unsigned byte that is this character. longword-int-dest-length OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Size of the destination area in bytes. The longword-int-dest- length argument is a signed longword containing this size. The value of longword-int-dest-length may range from 0 through 2,147,483,647. destination-array OpenVMS usage:vector_byte_unsigned type: byte (unsigned) access: write only mechanism: by reference, array reference Address into which source-array is moved. The destination-array argument is the address of an unsigned byte array into which OTS$MOVE5 writes the source data. 3 OTS$MULCx The Complex Multiplication routines calculate the complex product of two complex values. Format OTS$MULCD_R3 complex-multiplier ,complex-multiplicand (VAX only) OTS$MULCG_R3 complex-multiplier ,complex-multiplicand OTS$MULCT_R3 complex-multiplier ,complex-multiplicand OTS$MULCS complex-multiplier ,complex-multiplicand 4 Returns OpenVMS usage:complex_number type: D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex, access: write only mechanism: by value Complex result of multiplying two complex numbers. OTS$MULCD_ R3 returns a D-floating complex number. OTS$MULCG_R3 returns a G-floating complex number. OTS$MULCS returns an IEEE S-Floating complex number. OTS$MULCT_R3 returns an IEEE T-floating complex number. 4 Arguments complex-multiplier OpenVMS usage:complex_number type: D_floating complex, G_floating complex, S_floating complex, S_floating complex access: read only mechanism: by value Complex multiplier. The complex-multiplier argument contains the complex multiplier. For OTS$MULCD_R3, complex-multiplier is a D-floating complex number. For OTS$MULCG_R3, complex-multiplier is a G-floating complex number. For OTS$MULCS, complex-multiplier is a IEEE S-Floating complex number. For OTS$MULCT_R3, complex- multiplier is an IEEE T-floating complex number. complex-multiplicand OpenVMS usage:complex_number type: D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex access: read only mechanism: by value Complex multiplicand. The complex-multiplicand argument contains the complex multiplicand. For OTS$MULCD_R3, complex-multiplicand is a D-floating complex number. For OTS$MULCG_R3, complex- multiplicand is a G-floating complex number. For OTS$MULCS, complex-multiplicand is an IEEE S-floating complex number. For OTS$MULCT_R3, complex-multiplicand is an IEEE T-floating complex number. 3 OTS$POWCxCx The Raise a Complex Base to a Complex Floating-Point Exponent routines raise a complex base to a complex exponent. Format OTS$POWCC complex-base ,complex-exponent-value OTS$POWCDCD_R3 complex-base ,complex-exponent-value (VAX only) OTS$POWCGCG_R3 complex-base ,complex-exponent-value OTS$POWCSCS complex-base ,complex-exponent-value OTS$POWCTCT_R3 complex-base ,complex-exponent-value 4 Returns OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex access: write only mechanism: by value Result of raising a complex base to a complex exponent. OTS$POWCC returns an F-floating complex number. OTS$POWCDCD_R3 returns a D-floating complex number. OTS$POWCGCG_R3 returns a G-floating complex number. OTS$POWCSCS returns an IEEE S-floating complex number. OTS$POWCTCT_R3 returns an IEEE T-floating complex number. 4 Arguments complex-base OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex access: read only mechanism: by value Complex base. The complex-base argument contains the value of the base. For OTS$POWCC, complex-base is an F-floating complex number. For OTS$POWCDCD_R3, complex-base is a D-floating complex number. For OTS$POWCGCG_R3, complex-base is a G-floating complex number. For OTS$POWCSCS, complex-base is an IEEE S-floating complex number. For OTS$POWCTCT_R3, complex-base is an IEEE T- floating complex number. complex-exponent-value OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex access: read only mechanism: by value Complex exponent. The complex-exponent-value argument contains the value of the exponent. For OTS$POWCC, complex-exponent-value is an F-floating complex number. For OTS$POWCDCD_R3, complex- exponent-value is a D-floating complex number. For OTS$POWCGCG_ R3, complex-exponent-value is a G-floating complex number. For OTS$POWCSCS, complex-exponent-value is an IEEE S-floating complex number. For OTS$POWCTCT_R3, complex-exponent-value is an IEEE T-floating complex number. 3 OTS$POWCxJ The Raise a Complex Base to a Signed Longword Integer Exponent routines return the complex result of raising a complex base to an integer exponent. Format OTS$POWCJ complex-base ,longword-integer-exponent OTS$POWCDJ_R3 complex-base ,longword-integer-exponent (VAX only) OTS$POWCGJ_R3 complex-base ,longword-integer-exponent (VAX only) OTS$POWCSJ complex-base ,longword-integer-exponent OTS$POWCTJ_R3 complex-base ,longword-integer-exponent 4 Returns OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, IEEE S_floating complex, IEEE T_floating complex access: write only mechanism: by value Complex result of raising a complex base to an integer exponent. OTS$POWCJ returns an F-floating complex number. OTS$POWCDJ_R3 returns a D-floating complex number. OTS$POWCGJ_R3 returns a G- floating complex number. OTS$POWCGS_R3 returns an IEEE S-floating complex number. OTS$POWCGT_R3 returns an IEEE T-floating complex number. In each format, the result and base are of the same data type. 4 Arguments complex-base OpenVMS usage:complex_number type: F_floating complex, D_floating complex, G_floating complex, S_floating complex, T_floating complex, access: read only mechanism: by value Complex base. The complex-base argument contains the complex base. For OTS$POWCJ, complex-base is an F-floating complex number. For OTS$POWCDJ_R3, complex-base is a D-floating complex number. For OTS$POWCGJ_R3, complex-base is a G-floating complex number. For OTS$POWCSJ, complex-base is an IEEE S-floating complex number. For OTS$POWCTJ_R3, complex-base is an IEEE T- floating complex number. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent. The longword-integer-exponent argument is a signed longword containing the exponent. 3 OTS$POWDD The Raise a D-Floating Base to a D-Floating Exponent routine raises a D-floating base to a D-floating exponent. Format OTS$POWDD D-floating-point-base ,D-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: D_floating access: write only mechanism: by value Result of raising a D-floating base to a D-floating exponent. 4 Arguments D-floating-point-base OpenVMS usage:floating_point type: D_floating access: read only mechanism: by value Base. The D-floating-point-base argument is a D-floating number containing the base. D-floating-point-exponent OpenVMS usage:floating_point type: D_floating access: read only mechanism: by value Exponent. The D-floating-point-exponent argument is a D-floating number that contains the exponent. 3 OTS$POWDJ The Raise a D-Floating Base to a Longword Exponent routine raises a D-floating base to a longword exponent. Format OTS$POWDJ D-floating-point-base ,longword-integer-exponent 4 Returns OpenVMS usage:floating_point type: D_floating access: write only mechanism: by value Result of raising a D-floating base to a longword exponent. 4 Arguments D-floating-point-base OpenVMS usage:floating_point type: D_floating access: read only mechanism: by value Base. The D-floating-point-base argument is a D-floating number containing the base. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent. The longword-integer-exponent argument is a signed longword that contains the signed longword integer exponent. 3 OTS$POWDR The Raise a D-Floating Base to an F-Floating Exponent routine raises a D-floating base to an F-floating exponent. Format OTS$POWDR D-floating-point-base ,F-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: D_floating access: write only mechanism: by value Result of raising a D-floating base to an F-floating exponent. 4 Arguments D-floating-point-base OpenVMS usage:floating_point type: D_floating access: read only mechanism: by value Base. The D-floating-point-base argument is a D-floating number containing the base. F-floating-point-exponent OpenVMS usage:floating_point type: F_floating access: read only mechanism: by value Exponent. The F-floating-point-exponent argument is an F-floating number that contains the exponent. 3 OTS$POWGG The Raise a G-Floating Base to a G-Floating Exponent routine raises a G-floating base to a G-floating exponent. Format OTS$POWGG G-floating-point-base ,G-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: G_floating access: write only mechanism: by value Result of raising a G-floating base to a G-floating exponent. 4 Arguments G-floating-point-base OpenVMS usage:floating_point type: G_floating access: read only mechanism: by value Base that OTS$POWGG raises to a G-floating exponent. The G- floating-point-base argument is a G-floating number containing the base. G-floating-point-exponent OpenVMS usage:floating_point type: G_floating access: read only mechanism: by value Exponent to which OTS$POWGG raises the base. The G-floating- point-exponent argument is a G-floating number containing the exponent. 3 OTS$POWGJ The Raise a G-Floating Base to a Longword Exponent routine raises a G-floating base to a longword exponent. Format OTS$POWGJ G-floating-point-base ,longword-integer-exponent 4 Returns OpenVMS usage:floating_point type: G_floating access: write only mechanism: by value Result of raising a G-floating base to a longword exponent. 4 Arguments G-floating-point-base OpenVMS usage:floating_point type: G_floating access: read only mechanism: by value Base that OTS$POWGJ raises to a longword exponent. The G- floating-point-base argument is a G-floating number containing the base. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent to which OTS$POWGJ raises the base. The longword- integer-exponent argument is a signed longword containing the exponent. 3 OTS$POWHH_R3 On VAX systems, the Raise an H-Floating Base to an H-Floating Exponent routine raises an H-floating base to an H-floating exponent. Format OTS$POWHH_R3 H-floating-point-base ,H-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: H_floating access: write only mechanism: by value Result of raising an H-floating base to an H-floating exponent. 4 Arguments H-floating-point-base OpenVMS usage:floating_point type: H_floating access: read only mechanism: by value Base. The H-floating-point-base argument is an H-floating number containing the base. H-floating-point-exponent OpenVMS usage:floating_point type: H_floating access: read only mechanism: by value Exponent. The H-floating-point-exponent argument is an H-floating number that contains the H-floating exponent. 3 OTS$POWHJ_R3 On VAX systems, the Raise an H-Floating Base to a Longword Exponent routine raises an H-floating base to a longword exponent. Format OTS$POWHJ_R3 H-floating-point-base ,longword-integer-exponent 4 Returns OpenVMS usage:floating_point type: H_floating access: write only mechanism: by value Result of raising an H-floating base to a longword exponent. 4 Arguments H-floating-point-base OpenVMS usage:floating_point type: H_floating access: read only mechanism: by value Base. The H-floating-point-base argument is an H-floating number containing the base. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent. The longword-integer-exponent argument is a signed longword that contains the signed longword exponent. 3 OTS$POWII The Raise a Word Base to a Word Exponent routine raises a word base to a word exponent. Format OTS$POWII word-integer-base ,word-integer-exponent 4 Returns OpenVMS usage:word_signed type: word (signed) access: write only mechanism: by value Result of raising a word base to a word exponent. 4 Arguments word-integer-base OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Base. The word-integer-base argument is a signed word containing the base. word-integer-exponent OpenVMS usage:word_signed type: word (signed) access: read only mechanism: by value Exponent. The word-integer-exponent argument is a signed word containing the exponent. 3 OTS$POWJJ The Raise a Longword Base to a Longword Exponent routine raises a signed longword base to a signed longword exponent. Format OTS$POWJJ longword-integer-base ,longword-integer-exponent 4 Returns OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by value Result of raising a signed longword base to a signed longword exponent. 4 Arguments longword-integer-base OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Base. The longword-integer-base argument is a signed longword containing the base. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent. The longword-integer-exponent argument is a signed longword containing the exponent. 3 OTS$POWLULU The Raise an Unsigned Longword Base to an Unsigned Longword Exponent routine raises an unsigned longword integer base to an unsigned longword integer exponent. Format OTS$POWLULU unsigned-lword-int-base, unsigned-lword-int-exponent 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value Result of raising an unsigned longword integer base to an unsigned longword integer exponent. 4 Arguments unsigned-lword-int-base OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Unsigned longword integer base. The unsigned-lword-int-base argument contains the value of the integer base. unsigned-lword-int-exponent OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Unsigned longword integer exponent. The unsigned-lword-int- exponent argument contains the value of the integer exponent. 3 OTS$POWRD The Raise an F-Floating Base to a D-Floating Exponent routine raises an F-floating base to a D-floating exponent. Format OTS$POWRD F-floating-point-base ,D-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: D_floating access: write only mechanism: by value Result of raising an F-floating base to a D-floating exponent. 4 Arguments F-floating-point-base OpenVMS usage:floating_point type: F_floating access: read only mechanism: by value Base. The F-floating-point-base argument is an F-floating number containing the base. D-floating-point-exponent OpenVMS usage:floating_point type: D_floating access: read only mechanism: by value Exponent. The D-floating-point-exponent argument is a D-floating number that contains the exponent. 3 OTS$POWRJ The Raise an F-Floating Base to a Longword Exponent routine raises an F-floating base to a longword exponent. Format OTS$POWRJ F-floating-point-base ,longword-integer-exponent 4 Returns OpenVMS usage:floating_point type: F_floating access: write only mechanism: by value Result of raising an F-floating base to a longword exponent. 4 Arguments F-floating-point-base OpenVMS usage:floating_point type: F_floating access: read only mechanism: by value Base. The F-floating-point-base argument is an F-floating number containing the base. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent. The longword-integer-exponent argument is a signed longword that contains the longword exponent. 3 OTS$POWRR The Raise an F-Floating Base to an F-Floating Exponent routine raises an F-floating base to an F-floating exponent. Format OTS$POWRR F-floating-point-base ,F-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: F_floating access: write only mechanism: by value Result of raising an F-floating base to an F-floating exponent. 4 Arguments F-floating-point-base OpenVMS usage:floating_point type: F_floating access: read only mechanism: by value Base. The F-floating-point-base argument is an F-floating number containing the base. F-floating-point-exponent OpenVMS usage:floating_point type: F_floating access: read only mechanism: by value Exponent. The F-floating-point-exponent argument is an F-floating number that contains the exponent. 3 OTS$POWSJ The Raise an IEEE S-Floating Base to a Longword Exponent routine raises an IEEE S-floating base to a longword exponent. Format OTS$POWSJ S-floating-point-base ,longword-integer-exponent 4 Returns OpenVMS usage:floating_point type: S_floating access: write only mechanism: by value Result of raising an IEEE S-floating base to a longword exponent. 4 Arguments S-floating-point-base OpenVMS usage:floating_point type: S_floating access: read only mechanism: by value Base. The S-floating-point-base argument is an IEEE S-floating number containing the base. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent. The longword-integer-exponent argument is a signed longword that contains the longword exponent. 3 OTS$POWSS The Raise an IEEE S-Floating Base to an IEEE S-Floating Exponent routine raises a IEEE S-floating base to an IEEE S-floating exponent. Format OTS$POWSS S-floating-point-base ,S-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: IEEE S_floating access: write only mechanism: by value Result of raising an IEEE S-floating base to an IEEE S-floating exponent. 4 Arguments S-floating-point-base OpenVMS usage:floating_point type: IEEE S_floating access: read only mechanism: by value Base that OTS$POWSS raises to an IEEE S-floating exponent. The S-floating-point-base argument is an IEEE S-floating number containing the base. S-floating-point-exponent OpenVMS usage:floating_point type: IEEE S_floating access: read only mechanism: by value Exponent to which OTS$POWSS raises the base. The S-floating- point-exponent argument is an IEEE S-floating number containing the exponent. 3 OTS$POWTJ The Raise a T-Floating base to a Longword Exponent routine raises an IEEE T-floating base to a longword exponent. Format OTS$POWTJ T-floating-point-base ,longword-integer-exponent 4 Returns OpenVMS usage:floating_point type: IEEE T_floating access: write only mechanism: by value Result of raising an IEEE T-floating base to a longword exponent. 4 Arguments T-floating-point-base OpenVMS usage:floating_point type: IEEE T_floating access: read only mechanism: by value Base. The T-floating-point-base argument is an IEEE T-floating number containing the base. longword-integer-exponent OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by value Exponent. The longword-integer-exponent argument is a signed longword that contains the longword exponent. 3 OTS$POWTT The Raise an IEEE T-Floating Base to an IEEE T-Floating Exponent routine raises an IEEE T-floating base to an IEEE T-floating exponent. Format OTS$POWTT T-floating-point-base ,T-floating-point-exponent 4 Returns OpenVMS usage:floating_point type: IEEE T_floating access: write only mechanism: by value Result of raising an IEEE T-floating base to an IEEE T-floating exponent. 4 Arguments T-floating-point-base OpenVMS usage:floating_point type: IEEE T_floating access: read only mechanism: by value Base that OTS$POWTT raises to an IEEE T-floating exponent. The T-floating-point-base argument is an IEEE T-floating number containing the base. T-floating-point-exponent OpenVMS usage:floating_point type: IEEE T_floating access: read only mechanism: by value Exponent to which OTS$POWTT raises the base. The T-floating- point-exponent argument is an IEEE T-floating number containing the exponent. 3 OTS$POWxLU The Raise a Floating-Point Base to an Unsigned Longword Integer Exponent routines raise a floating-point base to an unsigned longword integer exponent. Format OTS$POWRLU floating-point-base ,unsigned-lword-int-exponent OTS$POWDLU floating-point-base ,unsigned-lword-int-exponent OTS$POWGLU floating-point-base ,unsigned-lword-int-exponent OTS$POWSLU floating-point-base ,unsigned-lword-int-exponent OTS$POWTLU floating-point-base ,unsigned-lword-int-exponent OTS$POWHLU_R3 floating-point-base ,unsigned-lword-int-exponent (VAX only) 4 Returns OpenVMS usage:floating_point type: F_floating, D_floating, G_floating, H_floating, IEEE S_floating, IEEE T_floating access: write only mechanism: by value Result of raising a floating-point base to an unsigned longword integer exponent. OTS$POWRLU returns an F-floating number. OTS$POWDLU returns a D-floating number. OTS$POWGLU returns a G-floating number. OTS$POWSLU returns an IEEE S-floating number. OTS$POWTLU returns an IEEE T-floating number. On VAX systems, OTS$POWHLU_R3 returns an H-floating number. 4 Arguments floating-point-base OpenVMS usage:floating_point type: F_floating, D_floating, G_floating, H_floating, IEEE S_floating, IEEE T_floating access: read only mechanism: by value Floating-point base. The floating-point-base argument contains the value of the base. For OTS$POWRLU, floating-point-base is an F-floating number. For OTS$POWDLU, floating-point-base is a D-floating number. For OTS$POWGLU, floating-point-base is a G- floating number. For OTS$POWHLU_R3, floating-point-base is an H-floating number. For OTS$POWSLU, floating-point-base is an IEE S-floating number. For OTS$POWTLU, floating-point-base is an IEEE T-floating number. unsigned-lword-int-exponent OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Integer exponent. The unsigned-lword-int-exponent argument contains the value of the unsigned longword integer exponent. 3 OTS$SCOPY_DXDX The Copy a Source String Passed by Descriptor to a Destination String routine copies a source string to a destination string. Both strings are passed by descriptor. Format OTS$SCOPY_DXDX source-string ,destination-string 4 Corresponding_JSB_Entry_Point OTS$SCOPY_DXDX6 4 Returns OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by value Number of bytes not moved to the destination string if the length of source-string is greater than the length of destination- string. The value is 0 (zero) otherwise. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string. The source-string argument is the address of a descriptor pointing to the source string. The descriptor class can be unspecified, fixed length, dynamic, scalar decimal, array, noncontiguous array, or varying. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string. The destination-string argument is the address of a descriptor pointing to the destination string. The class field determines the appropriate action. 3 OTS$SCOPY_R_DX The Copy a Source String Passed by Reference to a Destination String routine copies a source string passed by reference to a destination string. Format OTS$SCOPY_R_DX word-int-source-length-val ,source-string-address ,destination-string 4 Corresponding_JSB_Entry_Point OTS$SCOPY_R_DX6 4 Returns OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by value Number of bytes not moved to the destination string if the length of the source string pointed to by source-string-address is greater than the length of destination-string. Otherwise, the value is 0 (zero). 4 Arguments word-int-source-length-val OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by value Length of the source string. The word-int-source-length-val argument is an unsigned word integer containing the length of the source string. source-string-address OpenVMS usage:char_string type: character string access: read only mechanism: by reference Source string. The source-string-address argument is the address of the source string. destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string. The destination-string argument is the address of a descriptor pointing to the destination string. OTS$SCOPY_R_DX determines the appropriate action based on the descriptor's CLASS field. The descriptor's LENGTH field alone or both the POINTER and LENGTH fields can be modified if the string is dynamic. For varying strings, the string's current length (CURLEN) is rewritten. 3 OTS$SFREE1_DD The Strings, Free One Dynamic routine returns one dynamic string area to free storage. Format OTS$SFREE1_DD dynamic-descriptor 4 Corresponding_JSB_Entry_Point OTS$SFREE1_DD6 4 Returns None. 4 Argument dynamic-descriptor OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: modify mechanism: by reference Dynamic string descriptor. The dynamic-descriptor argument is the address of the dynamic string descriptor. The descriptor is assumed to be dynamic and its class field is not checked. 3 OTS$SFREEN_DD The Free n Dynamic Strings routine takes as input a vector of one or more dynamic string areas and returns them to free storage. Format OTS$SFREEN_DD descriptor-count-value ,first-descriptor 4 Corresponding_JSB_Entry_Point OTS$SFREEN_DD6 4 Returns None. 4 Arguments descriptor-count-value OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Number of adjacent descriptors to be flagged as having no allocated area (the descriptor's POINTER and LENGTH fields contain 0) and to have their allocated areas returned to free storage by OTS$SFREEN_DD. The descriptor-count-value argument is an unsigned longword containing this number. first-descriptor OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: modify mechanism: by reference First string descriptor of an array of string descriptors. The first-descriptor argument is the address of the first string descriptor. The descriptors are assumed to be dynamic, and their class fields are not checked. 3 OTS$SGET1_DD The Get One Dynamic String routine allocates a specified number of bytes of dynamic virtual memory to a specified string descriptor. Format OTS$SGET1_DD word-integer-length-value ,dynamic-descriptor 4 Corresponding_JSB_Entry_Point OTS$SGET1_DD_R6 4 Returns None. 4 Arguments word-integer-length-value OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by value Number of bytes to be allocated. The word-integer-length-value argument contains the number of bytes. The amount of storage allocated is automatically rounded up. If the number of bytes is zero, a small number of bytes is allocated. dynamic-descriptor OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: modify mechanism: by reference Dynamic string descriptor to which the area is to be allocated. The dyn-str argument is the address of the dynamic string descriptor. The CLASS field is not checked but it is set to dynamic (CLASS = 2). The LENGTH field is set to word-integer- length-value and the POINTER field is set to the string area allocated (first byte beyond the header). 2 PPL$ 3 PPL$ADJUST_QUORUM The Adjust Barrier Quorum routine increments or decrements the quorum associated with a barrier. Format PPL$ADJUST_QUORUM barrier-id ,amount 4 Arguments barrier-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the barrier. The barrier-id argument is the address of an unsigned longword containing the barrier identifier. Barrier-id is returned by PPL$CREATE_BARRIER. amount OpenVMS usage word_signed type word (signed) access read only mechanism by reference Value to add to the barrier quorum. The amount argument is the address of a signed word containing the amount. You can specify a negative value to decrement the quorum. 3 PPL$ADJUST_SEMAPHORE_MAXIMUM The Adjust a Semaphore Maximum routine increments or decrements the maximum associated with a semaphore. Format PPL$ADJUST_SEMAPHORE_MAXIMUM semaphore-id ,amount 4 Arguments semaphore-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the semaphore. The semaphore-id argument is the address of an unsigned longword containing the identifier. amount OpenVMS usage word_signed type word (signed) access read only mechanism by reference Value to add to the semaphore maximum. The amount argument is the address of a signed word containing the amount. Specify a positive value for amount to increase the maximum; specify a negative value to decrease the maximum. 3 PPL$AWAIT_EVENT The Await Event Occurrence routine blocks the caller until an event occurs. Format PPL$AWAIT_EVENT event-id [,output] 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the event. The event-id argument is the address of an unsigned longword containing the identifier. The event-id is returned by PPL$CREATE_EVENT. output OpenVMS usage user_arg type longword (unsigned) access write only mechanism by reference Receives the event-param argument from PPL$TRIGGER_EVENT. The output argument is the address of an unsigned longword that receives the value of event-param. The value of event-param is copied to output when an event is triggered. 3 PPL$CREATE_APPLICATION The Form or Join a PPL$ Application routine informs the PPL$ facility that the calling process is forming or joining a parallel application. Format PPL$CREATE_APPLICATION [size] [,application-name] [,protection] [,flags] 4 Arguments size OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by reference Number of (512 byte) pages that PPL$ allocates for its internal data structures. The optional size argument is the address of an unsigned longword containing this size value. See the Description section for information about the default value. application-name OpenVMS usage char_string type character string access read only mechanism by descriptor The name of the application that the calling process will form or join. The optional application-name argument is the address of a descriptor pointing to a character string containing the name of the application. The application-name argument can contain up to 11 characters. protection OpenVMS usage file_protection type longword (unsigned) access read only mechanism by reference Numeric value representing the protection mask to be applied to the application. The optional protection argument is the address of an unsigned longword containing this numeric value. For more information, see the description of the $CRMPSC system service in the OpenVMS System Services Reference Manual. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Specifies options for forming or joining a PPL$ application. The flags argument is a longword bit mask containing the flags. Valid values for flags are as follows: PPL$M_ Form a new application only-do not join an FORMONLY existing application. If this flag is not specified, a process will join an application if it already exists. PPL$M_ Join an existing application only-do not form a JOINONLY new application. If this flag is not specified, a process will form an application if it does not already exist. PPL$M_PERM Form a permanent application in which data is maintained even though there are no active processes. By default, application data is lost when the last process in the application exits. Use of this flag requires PRMGBL privilege. PPL$M_SYSTEM Form or join a systemwide application. By default, the application is available only to processes running under the same group UIC. Use of this flag requires SYSGBL and SYSLCK privileges. 3 PPL$CREATE_BARRIER The Create a Barrier routine creates and initializes a barrier, and returns the barrier identifier. You use the barrier identifier to perform all operations on that barrier. Format PPL$CREATE_BARRIER barrier-id [,barrier-name] [,quorum] 4 Arguments barrier-id OpenVMS usage identifier type longword (unsigned) access write only mechanism by reference Identifier of the barrier. The barrier-id argument is the address of an unsigned longword containing the identifier. Barrier-id must be used in calls to the other barrier routines (listed in the Description section) to identify the barrier. barrier-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the barrier. The optional barrier-name argument is the address of a descriptor pointing to a character string containing the barrier name. The name of the barrier is arbitrary. If you do not specify this argument, or if you specify 0, an unnamed barrier is created. An arbitrary number of unnamed barriers may be created by a given application. quorum OpenVMS usage word_signed type word (signed) access read only mechanism by reference Number of participants required to terminate an active wait for this barrier. The quorum argument is the address of a signed word containing the quorum number. For example, a quorum value of 3 indicates that the first two callers of PPL$WAIT_AT_BARRIER specifying this barrier-id are blocked until a third caller calls PPL$WAIT_AT_BARRIER. At that point, all three participants are released for further processing. If you do not specify a value for quorum, a default value of 1 is assigned. 3 PPL$CREATE_EVENT The Create an Event routine creates an arbitrary user-defined event and returns the event identifier. You use the event identifier to perform all operations on that event. Format PPL$CREATE_EVENT event-id [,event-name] 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access write only mechanism by reference Identifier of the event. The event-id argument is the address of an unsigned longword containing the identifier. Event-id must be used in other calls to identify the event. event-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the event. The event-name argument is the address of a descriptor pointing to a character string containing the event name. The name of the event is entirely arbitrary. If you do not specify a value for event-name, or if you specify 0, a new unnamed event is created, which can be referenced only by its identifier. An arbitrary number of unnamed events can be created by a given application. 3 PPL$CREATE_SEMAPHORE The Create a Semaphore routine creates and initializes a semaphore with a waiting queue, and returns the semaphore identifier. You use the semaphore identifier to perform all operations on that semaphore. Format PPL$CREATE_SEMAPHORE semaphore-id [,semaphore-name] [,semaphore-maximum] [,semaphore-initial] 4 Arguments semaphore-id OpenVMS usage identifier type longword (unsigned) access write only mechanism by reference Identifier of the semaphore. The semaphore-id argument is the address of an unsigned longword containing the identifier. Semaphore-id must be used in other calls to identify the semaphore. semaphore-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the semaphore. The semaphore-name argument is the address of a descriptor pointing to a character string containing the semaphore name. The name of the semaphore is entirely arbitrary. If you do not specify a value for semaphore-name, or if you specify 0, a new unnamed semaphore is created. An arbitrary number of unnamed semaphores may be created by a given application. semaphore-maximum OpenVMS usage word_signed type word (signed) access read only mechanism by reference Maximum value of the semaphore. The semaphore-maximum argument is the address of a signed word containing the maximum value. This value must be nonnegative. If you do not supply a value for semaphore-maximum, a default value of 1 is used, thereby making it a binary semaphore. semaphore-initial OpenVMS usage word_signed type word (signed) access read only mechanism by reference Initial value of the semaphore. The semaphore-initial argument is the address of a signed word containing the initial value. This value must be less than or equal to the semaphore-maximum value. If you do not supply a value for semaphore-initial, a default value equal to semaphore-maximum is used. 3 PPL$CREATE_SHARED_MEMORY The Create Shared Memory routine creates (if necessary) and maps a section of memory that can be shared by multiple processes. Format PPL$CREATE_SHARED_MEMORY section-name ,memory-area [,flags] [,file-name] [,protection] 4 Arguments section-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the shared memory section you want to create. The section-name argument is the address of a descriptor pointing to the shared memory section name. memory-area OpenVMS usage vector_longword_unsigned type longword (unsigned) access modify mechanism by reference, array reference The area of memory into which the shared memory is mapped. The memory-area argument is the address of a two-longword array containing, in order, the length (in bytes) and the starting virtual address for the area of memory. If you specify the starting address as zero, the PPL$ facility selects the virtual address space so that each current process in the application can map the section to the same set of virtual addresses. PPL$CREATE_SHARED_MEMORY returns to this argument the actual length and starting virtual address of the shared memory created or mapped. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Specifies options for creating and mapping shared memory. The flags argument is the address of a longword bit mask containing the flag. Valid values are as follows: PPL$M_NOZERO Does not initialize the shared memory to zero. By default, PPL$CREATE_SHARED_MEMORY initializes the shared memory to zero. PPL$M_NOWRT Maps the shared memory with no write access (in other words, read only). By default, the shared memory is available with read/write access. PPL$M_NOUNI Names the shared memory a nonunique name. By default, PPL$CREATE_SHARED_MEMORY gives the specified shared memory a name unique to the application by using PPL$UNIQUE_NAME. PPL$M_PERM Creates permanent shared memory in which data is maintained even though there are no active processes. The default is determined by your call to PPL$CREATE_APPLICATION: if you specify the PPL$M_PERM flag in your call to PPL$CREATE_ APPLICATION, this behavior is the default and you do not need to specify PPL$M_PERM in your call to PPL$CREATE_SHARED_MEMORY. If you do not specify the PPL$M_PERM flag in your calls to PPL$CREATE_APPLICATION and PPL$CREATE_SHARED_ MEMORY, application data is lost when the last process in the application exits. Use of this flag requires PRMGBL privilege. PPL$M_SYSTEM Creates systemwide shared memory. The default is determined by your call to PPL$CREATE_APPLICATION: if you specify the PPL$M_SYSTEM flag in your call to PPL$CREATE_APPLICATION, this behavior is the default and you do not need to specify PPL$M_ SYSTEM in your call to PPL$CREATE_SHARED_MEMORY. If you do not specify the PPL$M_SYSTEM flag in your calls to PPL$CREATE_APPLICATION and PPL$CREATE_ SHARED_MEMORY, the application is available only to processes running under the same group UIC. Use of this flag requires the SYSGBL privilege. file-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the file used for backup storage of the shared memory. The file-name argument is the address of a descriptor pointing to the file name. The size of the resulting address space is the smaller of the following: o The specified section size o The size of the file being mapped If you do not specify a file name, PPL$CREATE_SHARED_MEMORY creates for backup storage a page file section instead of a disk file section. If you specify a file that does not exist, PPL$CREATE_SHARED_ MEMORY creates it. protection OpenVMS usage file_protection type longword (unsigned) access read only mechanism by reference Numeric value representing the protection mask to be applied to the shared memory. The optional protection argument is the address of an unsigned longword containing this numeric value. If you do not specify a value, the default is the value for protection specified in the call to PPL$CREATE_APPLICATION. For more information, see the description of the $CRMPSC system service in the OpenVMS System Services Reference Manual. 3 PPL$CREATE_SPIN_LOCK The Create Spin Lock routine creates and initializes a simple (spin) lock, and returns the lock identifier. You use that lock identifier to get and free the lock. Format PPL$CREATE_SPIN_LOCK lock-id [,lock-name] 4 Arguments lock-id OpenVMS usage identifier type longword (unsigned) access write only mechanism by reference Identifier of the newly created lock. The lock-id argument is the address of an unsigned longword containing the lock identifier. You must use lock-id when getting or freeing the lock. lock-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the lock. The lock-name argument is the address of a descriptor pointing to a character string containing the name. The name of the lock is entirely arbitrary. If you do not specify this argument, or if you specify 0, an unnamed lock is created. An arbitrary number of unnamed locks can be created by a given application. 3 PPL$CREATE_VM_ZONE The Create a New Virtual Memory Zone routine creates a new storage zone, according to specified arguments, which is available to all participants in the application. Format PPL$CREATE_VM_ZONE zone-id [,algorithm] [,algorithm-argument] [,flags] [,extend-size] [,initial-size] [,block-size] [,alignment] [,page-limit] [,smallest-block-size] [,zone-name] 4 Arguments zone-id OpenVMS usage identifier type longword (unsigned) access write only mechanism by reference Zone identifier. The zone-id argument is the address of a longword set to the zone identifier of the newly created zone. algorithm OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Algorithm. The algorithm argument is the address of a signed longword that represents the code for one of the LIB$VM algorithms: 1 LIB$K_VM_FIRST_ First fit FIT 2 LIB$K_VM_QUICK_ Quick fit, lookaside list FIT 3 LIB$K_VM_FREQ_ Frequent sizes, lookaside list SIZES 4 LIB$K_VM_FIXED Fixed size blocks If algorithm is not specified, a default of 1 (first fit) is used. algorithm-argument OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Algorithm argument. The algorithm-argument argument is the address of a signed longword that contains a value specific to the particular allocation algorithm. Algorithm Value QUICK_FIT The number of queues used. The number of queues must be between 1 and 128. FREQ_SIZES The number of cache slots used. The number of cache slots must be between 1 and 16. FIXED The fixed request size (in bytes) for each get or free. The request size must be greater than 0. FIRST_FIT Not used, may be omitted. 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 if you are using the first-fit algorithm. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Flags. The flags argument is the address of an unsigned longword that contains flag bits that control various options: Bit Value Description Bit LIB$M_VM_BOUNDARY_ Boundary tags for faster freeing 0 TAGS Adds a minimum of eight bytes to each block Bit LIB$M_VM_GET_FILL0 LIB$GET_VM; fill with bytes of 0 1 Bit LIB$M_VM_GET_FILL1 LIB$GET_VM; fill with bytes of FF 2 (hexadecimal) Bit LIB$M_VM_FREE_FILL0 LIB$FREE_VM; fill with bytes of 0 3 Bit LIB$M_VM_FREE_FILL1 LIB$FREE_VM; fill with bytes of FF 4 (hexadecimal) Bit LIB$M_VM_EXTEND_ Add extents to existing areas if 5 AREA possible Bits 6 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 OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Zone extend size. The extend-size argument is the address of a signed longword that contains the number of (512-byte) pages to be added to the zone each time it is extended. The value of extend-size must be between 1 and 1024. This is an optional argument. If extend-size is not specified, a default of 16 pages is used. NOTE Extend-size does not limit the number of blocks that can be allocated from the zone. The actual extension size is the greater of extend-size and the number of pages needed to satisfy the LIB$GET_VM call that caused the extend. initial-size OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Initial size for the zone. The initial-size argument is the address of a signed longword that contains the number of (512- byte) pages to be allocated for the zone as the zone is created. This is an optional argument. If initial-size is not specified or is specified as 0, no pages are allocated when the zone is created. The first call to LIB$GET_VM for the zone allocates extend-size pages. block-size OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Block size of the zone. The block-size argument is the address of a signed longword 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 OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Block alignment. The alignment argument is the address of a signed longword 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 OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Maximum page limit. The page-limit argument is the address of a signed longword that specifies the maximum number of (512-byte) pages that can be allocated for the zone. The value of page-limit must be between 0 and 32,767. 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 the OpenVMS operating system. If page-limit is specified, then initial-size must also be specified. smallest-block-size OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Smallest block size. The smallest-block-size argument is the address of a signed longword that specifies the smallest block size (in bytes) with a queue for the quick fit algorithm. If smallest-block-size is not specified, the default of block- size is used. That is, queues are provided for the first n multiples of block-size. zone-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name to be associated with the zone being created. The optional zone-name argument is the address of a descriptor pointing to a character string containing the zone name. If zone-name is not specified, the zone does not have an associated name. 3 PPL$CREATE_WORK_QUEUE The Create a Work Queue routine creates and initializes a work queue and returns the work queue identifier. Format PPL$CREATE_WORK_QUEUE queue-id [,queue-name] 4 Arguments queue-id OpenVMS usage identifier type longword (unsigned) access write only mechanism by reference The work queue identifier. The queue-id argument is the address of an unsigned longword containing the identifier. Queue-id must be used in calls to the other work queue routines to identify the work queue. queue-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the work queue. The optional queue-name argument is the address of a descriptor pointing to a character string containing the work queue name. The work queue name is case sensitive. If you do not specify this argument, or if you specify 0, an unnamed work queue is created. An arbitrary number of unnamed work queues may be created by a given application. 3 PPL$DECREMENT_SEMAPHORE The Decrement a Semaphore routine waits for a semaphore to have a value greater than 0, then decrements the value by 1 to indicate the allocation of a resource. Format PPL$DECREMENT_SEMAPHORE semaphore-id [,flags] [,spin] 4 Arguments semaphore-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the semaphore. The semaphore-id argument is the address of an unsigned longword containing the identifier. Semaphore-id is returned by PPL$CREATE_SEMAPHORE. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Bit mask specifying options for decrementing the semaphore. The flags argument is a longword bit mask containing the flag. The valid values for flags are as follows: PPL$M_NON_ Indicates that the caller is not to block if BLOCKING the resource is not available. The default is FALSE: the caller will block if resource is unavailable. PPL$M_SPIN_WAIT Indicates that the caller is never to block, but rather to always spin while waiting at this barrier. PPL$M_SPIN_ Indicates that the caller wishes to spin for COUNTED a given amount of instructions and then to block. The default is block immediately, do not spin at all. spin OpenVMS usage mask_longword type long (unsigned) access read only mechanism by reference This value must be specified when using the PPL$M_SPIN_COUNTED flag and represents a relative time that a process will spin before blocking. 3 PPL$DELETE_APPLICATION The Delete a PPL$ Application routine marks all shared memory for deletion and prevents additional processes from joining the application. Format PPL$DELETE_APPLICATION 3 PPL$DELETE_BARRIER The Delete a Barrier routine deletes a barrier and releases any storage associated with it. Format PPL$DELETE_BARRIER [barrier-id] [,barrier-name] 4 Arguments barrier-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the barrier. The optional barrier-id argument is the address of an unsigned longword containing the barrier identifier. barrier-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the barrier. The optional barrier-name argument is the address of a descriptor pointing to a character string containing the barrier name. 3 PPL$DELETE_EVENT The Delete an Event routine deletes an event and releases any storage associated with it. Format PPL$DELETE_EVENT [event-id] [,event-name] 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the event. The optional event-id argument is the address of an unsigned longword containing the event identifier. event-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the event. The optional event-name argument is the address of a descriptor pointing to a character string containing the event name. 3 PPL$DELETE_SEMAPHORE The Delete a Semaphore routine deletes a semaphore and releases any storage associated with it. Format PPL$DELETE_SEMAPHORE [semaphore-id] [,semaphore-name] 4 Arguments semaphore-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the semaphore. The optional semaphore-id argument is the address of an unsigned longword containing the semaphore identifier. semaphore-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the semaphore. The optional semaphore-name argument is the address of a descriptor pointing to a character string containing the semaphore name. 3 PPL$DELETE_SHARED_MEMORY The Delete Shared Memory routine deletes or unmaps from a global section that you created using the PPL$CREATE_SHARED_MEMORY routine. Optionally, this routine writes the contents of the global section to disk before deleting the section. Format PPL$DELETE_SHARED_MEMORY section-name [,memory-area] [,flags] 4 Arguments section-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the global section you want to delete. The section-name argument is the address of a descriptor pointing to a character string containing the global section name. memory-area OpenVMS usage vector_longword_unsigned type longword (unsigned) access read only mechanism by reference, array reference The area of memory into which the global section that you want to delete is mapped. The memory-area argument is the address of a two-longword array containing, in order, the length in bytes and the starting virtual address of the area of memory. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Bit mask specifying actions to be performed before deleting the global section. The flags argument is the address of a longword bit mask containing the flag. Valid values for flags are as follows: PPL$M_FLUSH Writes the global section to disk before deleting it. PPL$M_NOUNI Identifies the global section as having a nonunique name. By default, PPL$CREATE_SHARED_ MEMORY gives the specified global section a name unique to the application by using PPL$UNIQUE_ NAME. If you specified this value to give the global section a nonunique name when you called PPL$CREATE_SHARED_MEMORY, you must also specify it when you call PPL$DELETE_SHARED_MEMORY. 3 PPL$DELETE_SPIN_LOCK The Delete a Spin Lock routine deletes a spin lock and releases any storage associated with it. Format PPL$DELETE_SPIN_LOCK [lock-id] [,lock-name] 4 Arguments lock-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the lock. The optional lock-id argument is the address of an unsigned longword containing the lock identifier. lock-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the lock. The optional lock-name argument is the address of a descriptor pointing to a character string containing the lock name. 3 PPL$DELETE_VM_ZONE The Delete a Virtual Memory Zone routine deletes a storage zone and returns all pages owned by the zone to the application-wide page pool. Format PPL$DELETE_VM_ZONE [zone-id] [,zone-name] 4 Arguments zone-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the zone. The optional zone-id argument is the address of an unsigned longword containing the zone identifier. zone-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the zone. The optional zone-name argument is the address of a descriptor pointing to a character string containing the zone name. 3 PPL$DELETE_WORK_ITEM The Delete a Work Queue Item routine deletes a work item from a work queue. Format PPL$DELETE_WORK_ITEM queue-id ,work-item [,flags] 4 Arguments queue-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference The queue identifier. The queue-id argument is the address of an unsigned longword containing the identifier. work-item OpenVMS usage user_arg type longword (unsigned) access read only mechanism by value The value of the item to be deleted from the queue. The work-item argument is the address of an unsigned longword containing this value. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Specifies options for deleting items from a work queue. The optional flags argument is the address of a longword bit mask containing the flag. Valid values are as follows: PPL$M_DELETEALL Delete all items in the specified queue whose value matches work-item. By default, only the first item encountered is deleted. PPL$M_TAILFIRST Begin searching at the end of the queue and move toward the beginning. By default, the search begins at the beginning of the queue and moves toward the end. 3 PPL$DELETE_WORK_QUEUE The Delete a Work Queue routine deletes the specified work queue, and releases any storage associated with it. Format PPL$DELETE_WORK_QUEUE [queue-id] [,queue-name] [,flags] 4 Arguments queue-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference The work queue identifier. The optional queue-id argument is the address of an unsigned longword containing the identifier. queue-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the work queue. The optional queue-name argument is the address of a descriptor pointing to a character string containing the work queue name. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Specifies options for deleting a work queue. The optional flags argument is the address of a longword bit mask containing the flag. The valid value is as follows: PPL$M_FORCEDEL Delete the work queue regardless of whether it is empty. By default, PPL$ returns the error PPL$_ELEINUSE if you attempt to delete a work queue at which proceses are blocked or that contains work items. 3 PPL$DISABLE_EVENT The Disable Asynchronous Notification of an Event routine disables delivery to a process of notification of an event by either AST or signal. Format PPL$DISABLE_EVENT event-id 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the event. The event-id argument is the address of an unsigned longword containing the identifier. 3 PPL$ENABLE_EVENT_AST The Enable AST Notification of an Event routine specifies the address of an AST routine (and optionally an argument to that routine) to be delivered when an event occurs. Format PPL$ENABLE_EVENT_AST event-id ,astadr [,astprm] 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the event. The event-id argument is the address of an unsigned longword containing the identifier. Event-id is returned by PPL$CREATE_EVENT. astadr OpenVMS usage ast_procedure type procedure value access call without stack unwinding mechanism by reference AST routine. The astadr argument is a procedure value of the user's AST routine. This routine is called on the user's behalf when the event state becomes occurred. astprm OpenVMS usage user_arg type unspecified access read only mechanism by value AST value passed as the argument to the specified AST routine. The astprm argument is the address of a vector of unsigned longwords containing this optional value. If this argument is not specified, PPL$_EVENT_OCCURRED is the astprm for a user-created event. The astprm argument has special restrictions when used in conjunction with the PPL$ event routines. o For user-defined events, the AST-argument must point to a vector of two unsigned longwords. The first longword is a "context" reserved for the user; it is not read or modified by PPL$. The second longword receives the value specified by the event-param argument in the call to PPL$TRIGGER_EVENT that results in the delivery of this AST. o For PPL$-defined events (those not created by the user), the astprm argument must point to a vector of four unsigned longwords. The vector accommodates the following: - The user's "context" longword - The longword to receive the event's distinguishing condition value - The parameters to the PPL$-defined event (the "trigger" parameter) Because each of the predefined events takes two arguments, the vector that astprm points to must be four longwords in length. 3 PPL$ENABLE_EVENT_SIGNAL The Enable Signal Notification of an Event routine specifies a condition value to be signaled when the event occurs. Format PPL$ENABLE_EVENT_SIGNAL event-id [,signal-value] 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the event. The event-id argument is the address of an unsigned longword containing the identifier. Event-id is returned by PPL$CREATE_EVENT. signal-value OpenVMS usage user_arg type longword (unsigned) access read only mechanism by value Optional user-defined value to be signaled when the event occurs. The signal-value argument is an unsigned longword containing this value. 3 PPL$FIND_OBJECT_ID Given the name of a spin lock, semaphore, barrier, event, work queue, or shared memory zone, the Find Object Identification routine returns the identifier of the object associated with the name you specify. Format PPL$FIND_OBJECT_ID object-id ,object-name 4 Arguments object-id OpenVMS usage identifier type longword (unsigned) access modify mechanism by reference Object identifier to be returned. The object-id argument is the address of an unsigned longword that receives the associated identifier. object-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the object for which to return the associated identifier. The object-name argument is the address of a descriptor pointing to a character string containing the (user-defined) name of the object. 3 PPL$FLUSH_SHARED_MEMORY The Flush Shared Memory routine writes (flushes) to disk the contents of a global section that you created using the PPL$CREATE_SHARED_MEMORY routine. Only pages that have been modified are flushed to disk. Format PPL$FLUSH_SHARED_MEMORY section-name [,memory-area] [,flags] 4 Arguments section-name OpenVMS usage char_string type character string access read only mechanism by descriptor Name of the global section whose contents are to be written to disk. The section-name argument is the address of a descriptor pointing to a character string containing the global section name. memory-area OpenVMS usage vector_longword_unsigned type longword (unsigned) access read only mechanism by reference, array reference The area of memory into which the specified global section is mapped. The memory-area argument is the address of a two- longword array containing, in order, the length (in bytes) and the starting virtual address for the area of memory. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Bit mask specifying actions to perform before flushing the global section. The flags argument is the address of a longword bit mask containing the flag. The valid value for flags is as follows: PPL$M_NOUNI Identifies the global section as having a nonunique name. By default, PPL$CREATE_SHARED_MEMORY gives the specified global section a name unique to the application by using PPL$UNIQUE_NAME. If you specified this value to give the global section a nonunique name when you called PPL$CREATE_SHARED_ MEMORY, you must also specify it when you call PPL$FLUSH_SHARED_MEMORY. 3 PPL$GET_INDEX The Get Index of a Participant routine returns an index that is unique within the application. A value of zero signifies the participant that formed the application. The other participants in the application always return an index greater than zero. Format PPL$GET_INDEX participant-index 4 Arguments participant-index OpenVMS usage longword_unsigned type longword (unsigned) access write only mechanism by reference The index of the caller within this application. The participant- index argument is the address of an unsigned longword that contains this index. This index is assigned at process creation time and is unique for each participant. 3 PPL$INCREMENT_SEMAPHORE The Increment a Semaphore routine increments the value of the semaphore by 1, analogous to the signal protocol. If any other participants are blocked on a call to PPL$DECREMENT_SEMAPHORE for this semaphore, one is removed from the queue and awakened. The semaphore must have been created by PPL$CREATE_SEMAPHORE. Format PPL$INCREMENT_SEMAPHORE semaphore-id 4 Arguments semaphore-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the semaphore. The semaphore-id argument is the address of an unsigned longword containing the identifier. Semaphore-id is returned by PPL$CREATE_SEMAPHORE. 3 PPL$INDEX_TO_PID The Convert Participant Index to OpenVMS PID routine returns the OpenVMS PID of the process associated with the specified index. Format PPL$INDEX_TO_PID participant-index ,pid 4 Arguments participant-index OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by reference Index of the caller within this application. The participant- index argument is the address of an unsigned longword that contains this index. Participant-index is assigned at process creation time and is unique for each participant. pid OpenVMS usage longword_unsigned type longword (unsigned) access write only mechanism by reference PID (process identifier) of the OpenVMS process associated with the specified participant-index. The pid argument is the address of an unsigned longword that receives this PID. 3 PPL$INSERT_WORK_ITEM The Insert a Work Queue Item routine inserts a work item into the specified work queue. Format PPL$INSERT_WORK_ITEM queue-id ,work-item [,flags] [,priority] 4 Arguments queue-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference The queue identifier. The queue-id argument is the address of an unsigned longword containing the identifier. work-item OpenVMS usage user_arg type longword (unsigned) access read only mechanism by value A value to be entered into the queue. The work-item argument is an unsigned longword containing this value. The content of work-item is completely arbitrary. You may want to place single longword values into work-item (for example, the number of a function or task to be performed). You can also use work-item to pass a pointer to a data block. (This data block must reside in memory created by PPL$CREATE_SHARED_MEMORY or allocated from a shared memory zone created by PPL$CREATE_VM_ZONE.) flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Specifies options for inserting a work item into a work queue. The optional flags argument is the address of a longword bit mask containing the flag. The valid value is as follows: PPL$M_ATHEAD Insert item as the first of those items with the same priority (in other words, at the head of the priority). By default, items are inserted after other items of the same priority. priority OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference Specifies the priority of the item being inserted. The optional priority argument is an unsigned longword containing the priority value for the item to be inserted. If unspecified, the default value is zero. A high numerical value indicates a high priority. 3 PPL$PID_TO_INDEX The Convert OpenVMS PID to Participant Index routine returns the PPL$-defined participant index of the process associated with the specified OpenVMS PID. Format PPL$PID_TO_INDEX pid ,participant-index 4 Arguments pid OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by reference PID (process identifier) of the OpenVMS process or subprocess whose participant index is to be obtained. The pid argument is the address of an unsigned longword that contains this PID. participant-index OpenVMS usage longword_unsigned type longword (unsigned) access write only mechanism by reference Participant index of the process or subprocess associated with the specified OpenVMS PID. The participant-index argument is the address of an unsigned longword that receives this index. Participant-index is assigned by the PPL$ facility at process creation time and is unique for each participant. 3 PPL$READ_BARRIER The Read a Barrier routine returns the specified barrier's current quorum and the number of participants currently waiting (blocked) at the barrier. The barrier must have been created by PPL$CREATE_BARRIER. Format PPL$READ_BARRIER barrier-id ,quorum ,waiters 4 Arguments barrier-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the specified event. The barrier-id argument is the address of an unsigned longword containing the identifier. Barrier-id is returned by PPL$CREATE_BARRIER. quorum OpenVMS usage word_signed type word (signed) access write only mechanism by reference Number of participants required to terminate a wait for this barrier. The quorum argument is the address of a signed word containing the quorum value. This argument returns the current quorum value that you set with PPL$CREATE_BARRIER, PPL$SET_ QUORUM, or PPL$ADJUST_QUORUM. waiters OpenVMS usage word_signed type word (signed) access write only mechanism by reference Number of participants currently waiting at this barrier. The waiters argument is the address of a signed word containing the number of waiting participants. 3 PPL$READ_EVENT The Read an Event State routine returns the current state of the specified event. The state can be occurred or not_occurred. Format PPL$READ_EVENT event-id ,occurred 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the specified event. The event-id argument is the address of an unsigned longword containing the identifier. Event-id is returned by PPL$CREATE_EVENT. occurred OpenVMS usage longword_unsigned type longword (unsigned) access write only mechanism by reference Receives the state of the specified event. The occurred argument is the address of an unsigned longword that receives the event state. This argument returns a value of true if the current state of the event is occurred, and returns false if the current state of the event is not_occurred. 3 PPL$READ_SEMAPHORE The Read Semaphore Values routine returns the current or maximum values, or both, of the specified counting semaphore. The semaphore must have been created by PPL$CREATE_SEMAPHORE. Format PPL$READ_SEMAPHORE semaphore-id [,semaphore-value] [,semaphore-maximum] 4 Arguments semaphore-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the specified semaphore. The semaphore-id argument is the address of an unsigned longword containing the identifier. Semaphore-id is returned by PPL$CREATE_SEMAPHORE. semaphore-value OpenVMS usage word_signed type word (signed) access write only mechanism by reference Receives information about the specified semaphore. The optional semaphore-value argument is the address of a signed word containing the current value of the semaphore or the number of blocked processes. If positive, semaphore-value contains the number of available resources associated with this semaphore; if negative, it contains the number of waiting processes. If the value returned is zero, there are no available resources and no waiting processes. semaphore-maximum OpenVMS usage word_signed type word (signed) access write only mechanism by reference Maximum value of the semaphore. The semaphore-maximum argument is the address of a signed word containing the maximum value of the semaphore specified by semaphore-id. 3 PPL$READ_SPIN_LOCK The Read a Spin Lock State routine returns the current state of a spin lock. The state can be seized or not_seized. Format PPL$READ_SPIN_LOCK lock-id ,seized 4 Arguments lock-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the specified spin lock. The lock-id argument is the address of an unsigned longword containing the identifier. seized OpenVMS usage longword_unsigned type longword (unsigned) access write only mechanism by reference Receives the state of the specified spin lock. The seized argument is the address of an unsigned longword that receives the spin lock state. This argument returns a value of true if the current state of the spin lock is seized, and it returns a value of false if the current state of the spin lock is not_seized. 3 PPL$READ_WORK_QUEUE The Read a Work Queue routine returns information about a work queue. Format PPL$READ_WORK_QUEUE queue-id [,queue-value] 4 Arguments queue-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference The queue identifier. The queue-id argument is the address of an unsigned longword containing the identifier. queue-value OpenVMS usage longword_signed type longword (signed) access write only mechanism by reference Receives information about the specified work queue. If positive, queue-value contains the number of items currently in the work queue; if negative, it contains the number of processes currently blocked (waiting for an item to be placed in the queue). If the value returned is zero, there are no work items in the queue and no blocked processes. The optional queue-value argument is the address of a signed longword that receives the number of work items or blocked processes. 3 PPL$RELEASE_SPIN_LOCK The Release Spin Lock routine relinquishes the spin lock by clearing the bit representing the lock. The lock must have been created by PPL$CREATE_SPIN_LOCK. Format PPL$RELEASE_SPIN_LOCK lock-id 4 Arguments lock-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the specified lock. The lock-id argument is the address of an unsigned longword containing the lock identifier. Lock-id is returned by PPL$CREATE_SPIN_LOCK. 3 PPL$REMOVE_WORK_ITEM The Remove a Work Queue Item routine removes the next item in order from a work queue. Format PPL$REMOVE_WORK_ITEM queue-id ,work-item [,flags] [,spin] 4 Arguments queue-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference The queue identifier. The queue-id argument is the address of an unsigned longword containing the identifier. work-item OpenVMS usage user_arg type longword (unsigned) access write only mechanism by reference Receives the value of the item that is removed from the work queue. The work-item argument is the address of an unsigned longword that receives the value of the item that is removed from the work queue. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Specifies options for removing an item from the work queue. The optional flags argument is the address of a longword bit mask containing the flag. Valid values are as follows: PPL$M_NON_ If the specified work queue is empty, return BLOCKING immediately with the PPL$_NOT_AVAILABLE status indicating that no items are available to be removed from the work queue. By default, if the work queue is empty the process hibernates until there is an item available to be removed from the work queue. PPL$M_FROMTAIL Remove item from the end (or tail) of the work queue. By default, this routine removes an item from the beginning (or head) of the work queue. PPL$M_SPIN_WAIT Indicates that the caller is never to block, but rather to always spin while waiting at this barrier. PPL$M_SPIN_ Indicates that the caller wishes to spin for COUNTED a given amount of instructions and then to block. The default is block immediately, do not spin at all. spin OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference This value must be specified when using the PPL$M_SPIN_COUNTED flag and represents a relative time that a process will spin before blocking. 3 PPL$RESET_EVENT The Reset an Event routine resets an event's state to not_ occurred. Format PPL$RESET_EVENT event-id 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the event. The event-id argument is the address of an unsigned longword containing the identifier. 3 PPL$SEIZE_SPIN_LOCK The Seize Spin Lock routine retrieves a simple (spin) lock by waiting in a spin loop until the lock is free. The lock must have been created by PPL$CREATE_SPIN_LOCK. Format PPL$SEIZE_SPIN_LOCK lock-id [,flags] 4 Arguments lock-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the lock to be seized. The lock-id argument is the address of an unsigned longword containing the lock identifier. Lock-id is returned by PPL$CREATE_SPIN_LOCK. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Bit mask specifying options for seizing the lock. The flags argument is a longword bit mask containing the flag. The valid value for flags is as follows: PPL$M_NON_ The lock is seized if and only if it can BLOCKING be done without causing the caller to wait (spin). (This can be useful in situations where the cost of waiting for a resource is not desirable, or if the caller merely intends to request immediate access to any one of a number of resources.) 3 PPL$SET_QUORUM The Set Barrier Quorum routine dynamically sets a value for the specified barrier's quorum. Format PPL$SET_QUORUM barrier-id ,quorum 4 Arguments barrier-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the barrier. The barrier-id argument is the address of the barrier identifier. Barrier-id is returned by PPL$CREATE_BARRIER. quorum OpenVMS usage word_signed type word (signed) access read only mechanism by reference The number of participants required to terminate an active wait for this barrier. The quorum argument is the address of a signed word containing the quorum number. For example, a quorum value of 3 indicates that the first two callers of PPL$WAIT_ AT_BARRIER specifying this barrier-id are blocked until a third participant calls PPL$WAIT_AT_BARRIER. At that point, all three are released for further processing. If you specify zero for quorum, the quorum is set to the number of processes currently in the application. The value of quorum must be positive or zero. 3 PPL$SET_SEMAPHORE_MAXIMUM The Set a Semaphore Maximum routine dynamically sets the maximum value of a semaphore. Format PPL$SET_SEMAPHORE_MAXIMUM semaphore-id ,semaphore-maximum 4 Arguments semaphore-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the semaphore. The semaphore-id argument is the address of an unsigned longword containing the identifier. semaphore-maximum OpenVMS usage word_signed type word (signed) access read only mechanism by reference New maximum value of the semaphore. The semaphore-maximum argument is the address of a signed word containing the maximum value. This value must be nonnegative. 3 PPL$SPAWN The Initiate Parallel Execution routine executes code in parallel with the caller by creating one or more subordinate threads of execution (OpenVMS subprocesses). Format PPL$SPAWN copies [,program-name] [,children-ids] [,flags] [,std-input-file] [,std-output-file] 4 Arguments copies OpenVMS usage longword_unsigned type longword (unsigned) access modify mechanism by reference Number of subordinates of the specified program to be executed concurrently. The copies argument is the address of an unsigned longword containing this number. Its value must be positive. If you specify a value greater than 1 for the copies argument, each copy created will have the same subprocess information (for example, standard input and output files). If you want to specify different information for each subprocess, call PPL$SPAWN once for each subprocess. On output, this parameter contains the number of subordinates actually created. This value differs from the requested number if an individual spawn attempt fails, for example, because of insufficient quotas. program-name OpenVMS usage logical_name type character string access read only mechanism by descriptor, fixed-length Name of the program (image) to be invoked. The program-name argument is the address of a descriptor pointing to a character string containing the file specification of the image. Program- name must have no more than 63 characters. If program-name contains a logical name, the equivalence name must be in a logical name table that the created subordinate can access. If you do not specify a program-name, the default is to execute in parallel the image being run by the caller. children-ids OpenVMS usage vector_longword_unsigned type longword (unsigned) access write only mechanism by reference, array reference Identifiers of each of the newly created subordinates. The children-ids argument is the address of a vector of longwords into which is written the index within the executing application of each subordinate successfully initiated by this call. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Bit mask specifying options for creating processes. The flags argument is a longword bit mask containing the flags. Valid values for flags are as follows: PPL$M_INIT_ If set, the caller of this routine and SYNCH all subordinates created by this call are synchronized to continue processing only after each and every subordinate created by this call has called PPL$CREATE_APPLICATION. (See the Description section for more information.) A failure of the created subordinate after it successfully starts but before its call to PPL$CREATE_APPLICATION can cause difficulties with the use of this flag value. PPL$M_NOCLISYM If set, the created processes do not inherit CLI symbols from the calling process. The default action is for created processes to inherit all currently defined CLI symbols. PPL$M_ If set, prompt strings are not prefixed by NOCONTROL carriage return/line feeds. The default action is to prefix any prompt string specified with a carriage return/line feed. PPL$M_NODEBUG Prevents the startup of the OpenVMS Debugger, even if the debugger was linked with the image. PPL$M_NOKEYPAD If set, created processes inherit the current keypad symbols and state from the calling process. The default action is that created processes do not inherit keypad symbols and state. PPL$M_NOLOGNAM If set, created processes do not inherit process logical names from the calling process. The default is for created processes to inherit all currently defined process logical names. PPL$M_NOTIFY If set, a message is broadcast to SYS$OUTPUT as each process terminates. This flag is ignored if the process is not interactive (for example, run in batch). std-input-file OpenVMS usage logical-name type character string access read only mechanism by descriptor File name of the file to serve as the standard input file in the created subordinates. The std-input-file argument is the address of a descriptor pointing to a character string containing the file name. If you do not specify a value for this argument, the subordinate inherits the creating participant's standard input file (SYS$INPUT). std-output-file OpenVMS usage logical-name type character string access read only mechanism by descriptor File name of the file to serve as the standard output file in the created subordinates. The std-output-file argument is the address of a descriptor pointing to a character string containing the file name. If you do not specify a value for this argument, the subordinate inherits the creating participant's standard output file (SYS$OUTPUT). 3 PPL$STOP The Stop a Participant routine terminates the execution of the specified participant in this application. Format PPL$STOP participant-index 4 Arguments participant-index OpenVMS usage longword_unsigned type longword (unsigned) access read only mechanism by reference PPL$-defined index of the participant to be terminated. The participant-index argument is the address of an unsigned longword containing the index. Participant-index is obtained by a call to PPL$SPAWN or PPL$GET_ INDEX. 3 PPL$TERMINATE The Abort PPL$ Participation routine ends the caller's participation in the application "prematurely"-that is, at some time before the caller actually completes its execution. Format PPL$TERMINATE [flags] 4 Arguments flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Bit mask specifying options for terminating access to PPL$. The flags argument is the address of a longword bit mask containing the flag. The flags argument accepts the following value: PPL$M_STOP_ Terminates all subordinates created by CHILDREN the caller in addition to terminating the caller itself. (PPL$ makes no effort to delete subordinates at process termination in the absence of a call to this routine specifying this flag value, but note that an OpenVMS subprocess is deleted when the parent terminates.) 3 PPL$TRIGGER_EVENT The Trigger an Event routine causes the event's state to become occurred. You control whether all pending actions for the event are processed (made to occur), or just one is processed. A pending action can be an AST, a signal (condition), or a wakeup. Format PPL$TRIGGER_EVENT event-id [,event-param] [,flags] 4 Arguments event-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the event. The event-id argument is the address of an unsigned longword containing the identifier. Event-id is returned by PPL$CREATE_EVENT. event-param OpenVMS usage user_arg type longword (unsigned) access read only mechanism by value An arbitrary value to be passed to all requests processed for the event as a result of the trigger, or, if there are no queued event notification requests for this event, to the first caller to enable event notification. The event-param argument is the address of an unsigned longword containing this value. The value of event-param is received by the output argument of PPL$AWAIT_ EVENT. If a participant enables delivery of an AST by calling PPL$ENABLE_EVENT_AST, this argument appears in the second longword of the vector specified by the astprm argument. If a participant enables delivery of a signal by calling PPL$ENABLE_ EVENT_SIGNAL, this argument appears as the third longword in the signal vector when the condition is raised. flags OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference Specifies options for triggering an event. The flags argument is the address of a longword bit mask containing the flag. The valid value for flags is as follows: PPL$M_NOTIFY_ONE Processes exactly one enabled event notification. By default, all pending actions are processed when the event state becomes occurred. 3 PPL$UNIQUE_NAME The Produce a Unique Name routine returns an application-unique name. A system-unique string specific to the calling application is appended to the string specified by the user. The resulting name is identical for all participants in the application, but different from those for all other applications on that system. Format PPL$UNIQUE_NAME name-string ,resultant-string [,resultant-length] [,flags] 4 Arguments name-string OpenVMS usage char_string type character string access read only mechanism by descriptor The user-supplied string to be appended by the 'TOP' processes' PID. When combined, they will provide a name unique to this application. resultant-string OpenVMS usage char_string type character string access write only mechanism by descriptor Resulting unique name. The resultant-string argument is the address of a descriptor pointing to a character string containing this name. Resultant-string consists of the name-string string and an appended system-unique string. resultant-length OpenVMS usage word_unsigned type word (unsigned) access write only mechanism by reference Length of the unique name returned as the resultant-string. The resultant-length argument is the address of an unsigned word containing this length. flags OpenVMS usage word_unsigned type longword (unsigned) access write only mechanism by reference Specifies whether the supplied name should be unique to the application, to the calling process, or to this particular call. The default is application-unique. The valid values for flags are as follows: PPL$M_PROC_UNIQUE Indicates that the caller wishes the returned name to be unique to the calling process. PPL$M_CALL_UNIQUE Indicates that the caller wishes the returned name to be unique to this particular call. 3 PPL$WAIT_AT_BARRIER The Synchronize at a Barrier routine causes the caller to wait at the specified barrier. The barrier is in effect from the time the first participant calls PPL$WAIT_AT_BARRIER until each member of the quorum has issued the call. At that time, the wait concludes and all are released for further execution. Format PPL$WAIT_AT_BARRIER barrier-id ,flags ,spin 4 Arguments barrier-id OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Identifier of the barrier. The barrier-id argument is the address of an unsigned longword containing the barrier identifier. Barrier-id is returned by PPL$CREATE_BARRIER. flags OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference Specifies options for the wait_at_barrier operation. The flags argument is the value of a longword bit mask containing the flag. The bit, when set, specifies the corresponding option. Valid values for flags are as follows: PPL$M_SPIN_WAIT Indicates that the caller is never to block, but rather to always spin while waiting at this barrier. PPL$M_SPIN_ Indicates that the caller wishes to spin for COUNTED a given amount of instructions and then to block. The default is block immediately, do not spin at all. spin OpenVMS usage identifier type long (unsigned) access read only mechanism by reference This value must be specified when using the PPL$M_SPIN_COUNTED flag and represents a relative time that a process will spin before blocking. 2 SMG$ 3 SMG$ADD_KEY_DEF The Add Key Definition routine adds a keypad key definition to a table of key definitions. Format SMG$ADD_KEY_DEF key-table-id ,key-name [,if-state] [,attributes] [,equivalence-string] [,state-string] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifies the key table to which you are adding a key definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier. The key table identifier argument is returned by the SMG$CREATE_ KEY_TABLE routine. key-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Identifies the key whose value you are defining. The key-name argument is the address of a descriptor pointing to this key name. The SMG$ADD_KEY_DEF routine changes the string to uppercase and removes trailing blanks. if-state OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Qualifies the value returned when key-name is pressed. The if- state argument is the address of a descriptor pointing to the state string. If if-state is specified, this definition of key-name is used only if the current state matches the specified if-state string. The if-state argument must be from 1 to 31 characters in length. If this argument is omitted, if-state defaults to the value DEFAULT. attributes OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Longword bit mask specifying additional attributes of this key definition. The attributes argument is the address of an unsigned longword that contains this attribute mask. If omitted, the mask is zero. Valid attributes are described in the following list: SMG$M_KEY_NOECHO If set, this bit specifies that equivalence-string is not to be echoed when this key is pressed. If clear, equivalence-string is echoed. If SMG$M_ KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored. SMG$M_KEY_TERMINATE If set, this bit specifies that when this key is pressed (as qualified by if- state) the input line is complete and more characters should not be accepted. If clear, more characters may be accepted. In other words, setting this bit causes equivalence-string to be treated as a terminator. SMG$M_KEY_LOCK If set, and if state-string is specified, the state name specified by state-string remains the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state- string remains in effect only for the next defined keystroke. SMG$M_KEY_PROTECTED If set, this bit specifies that this key definition cannot be modified or deleted. If clear, the key definition can be modified or deleted. The remaining bits are undefined and must be zero. It is possible to perform a logical OR operation on these values to set more than one attribute at a time. equivalence-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Character string to be substituted for the keystroke in the returned line. The equivalence-string argument is the address of a descriptor pointing to this equivalence string. The equivalence-string argument is displayed unless SMG$M_KEY_ NOECHO is set. If equivalence-string is omitted, no equivalence string is defined for this key. state-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Contains a new state name that becomes the current state when this key is pressed. The state-string argument is the address of a descriptor pointing to the new state string. If omitted, no new state is defined. If the current state is temporary (that is, if SMG$M_KEY_LOCKSTATE was not specified for the most recently pressed defined key), the current state-string becomes DEFAULT. 3 SMG$BEGIN_DISPLAY_UPDATE The Begin Batching of Display Updates routine saves, or batches, all output to a virtual display until a matching call to SMG$END_ DISPLAY_UPDATE is encountered. Format SMG$BEGIN_DISPLAY_UPDATE display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display for which output is to be batched. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. 3 SMG$BEGIN_PASTEBOARD_UPDATE The Begin Batching of Pasteboard Updates routine saves, or batches, all output to a pasteboard until a matching call to SMG$END_PASTEBOARD_UPDATE is encountered. Format SMG$BEGIN_PASTEBOARD_UPDATE pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard for which output is to be batched. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. 3 SMG$CANCEL_INPUT The Cancel Input Request routine immediately cancels any read- in-progress that was issued by SMG$READ_COMPOSED_LINE, SMG$READ_ KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY. Format SMG$CANCEL_INPUT keyboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual keyboard for which the input is to be canceled. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier. The keyboard identifier is returned by SMG$CREATE_VIRTUAL_ KEYBOARD. 3 SMG$CHANGE_PBD_CHARACTERISTICS The Change Pasteboard Characteristics routine lets you change the characteristics associated with a pasteboard. Format SMG$CHANGE_PBD_CHARACTERISTICS pasteboard-id [,desired-width] [,width] [,desired-height] [,height] [,desired-background-color] [,background-color] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard whose characteristics are to be changed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. desired-width OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference New width for the pasteboard. The desired-width argument is the address of a signed longword that contains the desired width. If omitted, the width does not change. width OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the physical width of the pasteboard. The width argument is the address of a signed longword into which is written the actual width of the pasteboard. If the terminal cannot be set exactly to desired-width, width may be larger than desired-width. If the physical width of the terminal is smaller than desired-width, width may be smaller than desired-width. desired-height OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference New height for the pasteboard. The desired-height argument is the address of a signed longword that contains the desired height of the pasteboard. If desired-height is omitted, the height does not change. height OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the physical height of the pasteboard. The height argument is the address of a signed longword into which is written the actual height of the pasteboard. If the terminal cannot be set exactly to desired-height, height may be larger than desired-height. If the physical height of the terminal is smaller than desired-height, height may be smaller than desired-height. desired-background-color OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Symbolic name for the desired background color. The desired- background-color argument is the address of an unsigned longword that contains the desired color. The symbols listed below are defined in $SMGDEF. Valid values for desired-background-color are as follows: SMG$C_COLOR_WHITE Light background SMG$C_COLOR_BLACK Dark background SMG$C_COLOR_BLUE Blue background SMG$C_COLOR_CYAN Cyan (green-blue) background SMG$C_COLOR_GREEN Green background SMG$C_COLOR_ Magenta background MAGENTA SMG$C_COLOR_RED Red background SMG$C_COLOR_YELLOW Yellow background SMG$C_COLOR_LIGHT White background SMG$C_COLOR_DARK Black background SMG$C_COLOR_USER1 User-defined background 1 SMG$C_COLOR_USER2 User-defined background 2 SMG$C_COLOR_USER3 User-defined background 3 SMG$C_COLOR_USER4 User-defined background 4 SMG$C_COLOR_USER5 User-defined background 5 SMG$C_COLOR_USER6 User-defined background 6 SMG$C_COLOR_USER7 User-defined background 7 SMG$C_COLOR_USER8 User-defined background 8 If you omit desired-background-color, or if the terminal hardware does not support the background color specified, the background color is not changed. background-color OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Receives the background color chosen. The background-color argument is the address of an unsigned longword into which is written the background color. This routine may return any of the values listed in the desired- background-color argument description or SMG$C_COLOR_UNKNOWN. If the desired-background-color argument is omitted, the value of background-color does not change. 3 SMG$CHANGE_RENDITION The Change Default Rendition routine changes the video attributes for all or part of a virtual display. Format SMG$CHANGE_RENDITION display-id ,start-row ,start-column ,number-of-rows ,number-of-columns [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display whose default rendition is to be changed. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Starting row position to receive the new rendition. The start-row argument is the address of a signed longword that contains the starting row number. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Starting column position to receive the new rendition. The start- column argument is the address of a signed longword that contains the starting column number. number-of-rows OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of rows to receive the new rendition. The number-of-rows argument is the address of a signed longword that contains the number of rows to be affected. number-of-columns OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of columns to receive the new rendition. The number- of-columns argument is the address of a signed longword that contains the number of columns to be affected. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$CHANGE_VIEWPORT The Change the Viewport Associated with a Virtual Display routine changes the size of an existing viewport in a virtual display. The text currently in the viewport is remapped to fit the new dimensions. Format SMG$CHANGE_VIEWPORT display-id [,viewport-row-start] [,viewport-column-start] [,viewport-number-rows] [,viewport-number-columns] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display containing the viewport to be changed. The display-id argument is the address of an unsigned longword containing this identifier. viewport-row-start OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional row number in the virtual display that will become row 1 in the changed viewport. The viewport-row-start argument is the address of a signed longword containing the row number. If omitted, the present viewport-row-start value is used. viewport-column-start OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional column number in the virtual display that will become column 1 in the changed viewport. The viewport-column-start argument is the address of a signed longword containing the column number. If omitted, the present viewport-column-start value is used. viewport-number-rows OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional number of rows in the changed viewport. The viewport- number-rows argument is the address of a signed longword containing the number of rows. If omitted, the present viewport- number-rows value is used. viewport-number-columns OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional number of columns in the changed viewport. The viewport- number-columns argument is the address of a signed longword containing the number of columns. If omitted, the present viewport-number-columns value is used. 3 SMG$CHANGE_VIRTUAL_DISPLAY The Change Virtual Display routine lets you change the dimensions, border, and video attributes of a virtual display. Format SMG$CHANGE_VIRTUAL_DISPLAY display-id [,number-of-rows] [,number-of-columns] [,display-attributes] [,video-attributes] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display whose attributes are to be changed. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. number-of-rows OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the new number of rows for the virtual display. The number-of-rows argument is the address of a signed longword that contains the number of rows in the virtual display. number-of-columns OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the new number of columns for the virtual display. The number-of-columns argument is the address of a signed longword that contains the number of columns in the virtual display. display-attributes OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the attributes of the virtual display. The display- attributes argument is the address of a longword bit mask that contains the display attributes. Valid values for display-attributes are as follows: SMG$M_BORDER Specifies a bordered display. If omitted, the display is not bordered. SMG$M_BLOCK_ Specifies a block bordered display. If BORDER omitted, the display is not bordered. SMG$M_DISPLAY_ Specifies that control characters such as CONTROLS carriage return and line feed are displayed as graphic characters, if your terminal supports them. SMG$M_TRUNC_ICON Specifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred. video-attributes OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the default rendition to be applied to all output in a virtual display, unless overridden by a call to a specific output routine. The video-attributes argument is the address of an unsigned longword that contains the video attributes mask. For example, a call to SMG$PUT_CHARS with an explicit rendition specified would override the default rendition. The bits that can be set for this argument are as follows: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, to the opposite of the current default rendition of the virtual display. SMG$M_UNDERLINE Displays underlined characters. SMG$M_INVISIBLE Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 You can specify any combination of attributes in a single call. All other bits are reserved for use by Compaq and must be 0. character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set specifier. Valid values are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS. 3 SMG$CHECK_FOR_OCCLUSION The Check for Occlusion routine checks to see whether a virtual display is covered (occluded) by another virtual display. Format SMG$CHECK_FOR_OCCLUSION display-id ,pasteboard-id ,occlusion-state 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be checked. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be checked. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. occlusion-state OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the value denoting whether the display is occluded. The occlusion-state argument is the address of a signed longword into which the occlusion state is written. Occlusion-state is set to 1 if the display is occluded or set to 0 if the display is not occluded on the specified pasteboard. If the procedure does not return SS$_NORMAL, the contents of occlusion-state are undefined. 3 SMG$CONTROL_MODE The Control Mode routine controls the mode of the pasteboard. This includes buffering, minimal updating, whether the screen is cleared when the pasteboard is deleted, and whether tab characters are used for screen formatting. Format SMG$CONTROL_MODE pasteboard-id [,new-mode] [,old-mode] [,buffer-size] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be changed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. new-mode OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the new control settings to be used. The optional new-mode argument is the address of an unsigned longword that contains the mode settings. A bit set to 1 forces that mode to be employed; a bit set to 0 inhibits that mode of operation. Valid settings are as follows: SMG$M_BUF_ENABLED Enables buffering. SMG$M_CLEAR_ Causes the Screen Management Facility to clear SCREEN the screen when the program exits if you have not previously deleted the pasteboard. SMG$M_IGNORE Allows you to delete the pasteboard even if batching is in effect. SMG$M_MINUPD Enables minimal update (the default). SMG$M_NOTABS Causes the Screen Management Facility not to use tab characters to format the screen. SMG$M_PROTECT Protect pasteboard operations from AST interrupts (the default). SMG$M_RELEASE_PBD Allows you to change the pasteboard size (using the SMG$CHANGE_PBD_CHARACTERISTICS routine) and prevents the Screen Management Facility from modifying anything on the screen outside of the smaller pasteboard. All other bits must be 0 and are reserved for future use by Compaq. old-mode OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Receives the control settings that were in effect before calling this procedure. The optional old-mode argument is the address of an unsigned longword into which the former mode settings are written. A bit set to 1 indicates that the specified mode was employed; a bit set to 0 indicates that the mode was inhibited. buffer-size OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Specifies the size of the buffer in bytes. The optional buffer- size argument is the address of an unsigned word that contains the size of the buffer. The buffer-size argument is used when buffering mode is enabled (SMG$M_BUF_ENABLED). The default and minimum buffer size is 256 bytes. The maximum value is 65535. The buffer-size value depends on user authorization file (UAF) values and is maximized with the SYSGEN parameter MAXBUF. 3 SMG$COPY_VIRTUAL_DISPLAY The Copy a Virtual Display routine creates a copy of an existing virtual display and assigns to it a new virtual display identifier. Format SMG$COPY_VIRTUAL_DISPLAY current-display-id ,new-display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments current-display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier of the virtual display to be replicated. The current-display-id argument is the address of the unsigned longword that contains the display identifier. new-display-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the display identifier of the newly created virtual display. The new-display-id argument is the address of the unsigned longword that receives the new display identifier. 3 SMG$CREATE_KEY_TABLE The Create Key Table routine creates a table for key definitions. Format SMG$CREATE_KEY_TABLE key-table-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument key-table-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the identifier of the newly created key table. The key- table-id argument is the address of an unsigned longword into which the key table identifier is written. 3 SMG$CREATE_MENU The Fill the Virtual Display with a Menu routine displays menu choices in the virtual display indicated, starting at the specified row. Format SMG$CREATE_MENU display-id ,choices [,menu-type] [,flags] [,row] [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier of the virtual display in which the menu is created. The display-id argument is the address of an unsigned longword containing this identifier. choices OpenVMS usage:static array of char_string type: character string access: read only mechanism: by descriptor Static array in which each element corresponds to an item to be displayed in the menu. The choices argument is the address of a descriptor pointing to this static array of character strings. Note that blank menu items are ignored. menu-type OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Optional bit mask specifying the type of menu to be displayed. The menu-type argument is the address of a longword bit mask that specifies this menu type. Valid values are as follows: SMG$K_BLOCK The menu items are displayed in matrix format (default). SMG$K_VERTICAL Each menu item is displayed on its own line. SMG$K_HORIZONTAL The menu items are displayed all on one line. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask specifying the attributes to be used for the menu. The flags argument is the address of an unsigned longword that contains the flag. Valid values are as follows: SMG$M_DOUBLE_ Double-spaced rows of menu items. The default SPACE is single spaced. SMG$M_FIXED_ Each menu item is in a fixed-length field. The FORMAT field is the size of the largest menu item. The default is compress. SMG$M_FULL_FIELD The full field is highlighted when you move within the menu using item keys. The default is that menu items only are highlighted. If you specify this flag value, it also implies SMG$M_FIXED_FORMAT. SMG$M_WIDE_MENU Wide characters are used in the menu items. The default is normal sized characters. SMG$M_WRAP_MENU The up arrow and down arrow keys cause the menu to wrap when the cursor is on the first or last rows of the menu. row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional row number in the specified virtual display at which the first menu item is displayed. The row argument is the address of a signed longword that contains this row number. If row is omitted, the first row of the virtual display's scrolling region is used. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be used when writing out the menu choices. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$CREATE_PASTEBOARD The Create a Pasteboard routine creates a pasteboard and returns its assigned pasteboard identifier. Format SMG$CREATE_PASTEBOARD pasteboard-id [,output-device] [,number-of-pasteboard-rows] [,number-of-pasteboard-columns] [,flags] [,type-of-terminal] [,device-name] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the identifier of the newly created pasteboard. The pasteboard-id argument is the address of an unsigned longword into which the new pasteboard identifier is written. output-device OpenVMS usage:device_name type: character string access: read only mechanism: by descriptor Specifies the file specification or logical name to which the output associated with this pasteboard will be written. The output-device argument is the address of a descriptor that points to the name of the output device. If omitted, output is sent to SYS$OUTPUT. number-of-pasteboard-rows OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the number of rows on the device specified in the output-device argument. The number-of-pasteboard-rows argument is the address of a signed longword into which is written the number of rows on the specified device, which will be the number of rows in the pasteboard. number-of-pasteboard-columns OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the number of columns on the device specified in the output-device argument. The number-of-pasteboard-columns argument is the address of a signed longword into which the number of columns on the specified device is written. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the attributes to be used in the pasteboard. The flags argument is the address of an unsigned longword that contains the flag. The default action is to clear the screen when the pasteboard is created. Valid values are as follows: SMG$M_KEEP_ The screen is not initially cleared. The CONTENTS Screen Management Facility works best when it can manage the entire screen. Therefore, using SMG$M_KEEP_CONTENTS is discouraged. SMG$M_WORKSTATION Calls DECterm to create a DECterm window if the Screen Management Facility is running on a workstation that is running DECwindows. If it is not running on a workstation that is running DECwindows, this flag is ignored. type-of-terminal OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Receives the SMG$ internal device type to which the output associated with this pasteboard will be written. The type-of- terminal argument is the address of an unsigned longword into which is written the terminal type. The returned values are as follows: SMG$K_UNKNOWN SMG$K_VTFOREIGN SMG$K_HARDCOPY SMG$K_VTTERMTABLE If a value other than SMG$K_VTTERMTABLE is returned, you must use SMG$SNAPSHOT to output the contents of the pasteboard. device-name OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the device name of the device on which the output associated with this pasteboard is written. The device-name argument is the address of a descriptor into which is written the device name. If you specify the SMG$M_WORKSTATION value to the flags argument, this argument returns the DECwindows terminal device name created by the Screen Management Facility for this pasteboard. (You can then specify the device name in a call to SMG$CREATE_VIRTUAL_ KEYBOARD to allow reading of input from the DECterm window.) Otherwise, the string specified by OUT_DEVICE is returned. 3 SMG$CREATE_SUBPROCESS The Create and Initialize a Subprocess routine creates a DCL subprocess and associates it with a virtual display. Format SMG$CREATE_SUBPROCESS display-id [,AST-routine] [,AST-argument] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display with which the newly created subprocess is associated. The display-id argument is the address of an unsigned longword containing this identifier. AST-routine OpenVMS usage:ast_procedure type: procedure value access: call without stack unwinding mechanism: by value Optional AST routine to be called when the currently executing command completes. The AST-routine argument is the routine's procedure value. The AST routine is called with five parameters. The first parameter is a pointer to a data structure that contains the display-id, AST-argument, and the command-status values. The remaining four parameters for the AST routine are R0, R1, PC, and PSL. The following figure illustrates the AST-routine parameters and the data structure pointed to by the first parameter. Parameters to AST Routine data structure +--------------------------------+ +------------------+ | address of data structure |------>| display-id | +--------------------------------+ +------------------+ | R0 | | AST-argument | +--------------------------------+ +------------------+ | R1 | | command-status | +--------------------------------+ +------------------+ | PC | +--------------------------------+ | PSL | +--------------------------------+ If the AST-routine argument is specified, the routine SMG$EXECUTE_COMMAND buffers any commands passed to it and executes them in order, calling the specified AST routine when each command completes. If the AST-routine argument is not specified, SMG$EXECUTE_COMMAND waits until the specified command completes before returning control to the user. AST-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value Optional argument you supply to the AST routine. The AST-argument parameter is an unsigned longword that contains the value to be passed to the AST routine. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional argument you supply to SMG$CREATE_SUBPROCESS. SMG$CREATE_SUBPROCESS calls LIB$SPAWN to create the subprocess. The flags argument lets you control some of the flags used in that call. Flags available to SMG$CREATE_SUBPROCESS correspond to flags in LIB$SPAWN as follows: SMG$CREATE_ LIB$SPAWN SUBPROCESS Flag Flag Function SMG$M_TRUSTED TRUSTED If this bit is set, it indicates a SPAWN command on behalf of the application. If this bit is not set, it indicates that the SPAWN command originates from the user. SPAWN commands originating from users are disallowed in captive accounts (DCL). SMG$M_AUTHPRIV AUTHPRIV If this bit is set, the subprocess inherits the caller's authorized privileges. If this bit is clear, the spawned processes' authorized mask is set equal to the caller's current (active) privilege mask. SMG$M_SUBSYSTEM SUBSYSTEM If this bit is set, a spawned process inherits protected subsystem IDs for the duration of LOGINOUT.EXE (used to map the command line interpreter). The IDs will be removed in the process of transferring control to the command language interpreter (CLI) (as a user mode $RUNDWN is performed). If this bit is clear, LOGINOUT does not execute under the subsystem IDs. The default is that none of these bits is set. See online Help or the OpenVMS RTL Library (LIB$) Manual for a complete description of LIB$SPAWN, these flags, and the security consideration surrounding their use. 3 SMG$CREATE_VIEWPORT The Create a Virtual Viewport routine creates a viewport and associates it with a virtual display. The location and size of the viewport are specified by the caller. Format SMG$CREATE_VIEWPORT display-id ,viewport-row-start ,viewport-column-start ,viewport-number-rows ,viewport-number-columns 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier of the virtual display associated with the newly created viewport. The display-id argument is the address of an unsigned longword containing this identifier. viewport-row-start OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Row number in the virtual display that will become row 1 in the viewport. The viewport-row-start argument is the address of a signed longword containing the row number. viewport-column-start OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Column number in the virtual display that will become column 1 in the viewport. The viewport-column-start argument is the address of a signed longword containing the column number. viewport-number-rows OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of rows in the viewport. The viewport-number-rows argument is the address of a signed longword containing the number of rows in the newly created viewport. viewport-number-columns OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of columns in the viewport. The viewport-number-columns argument is the address of a signed longword containing the number of columns in the newly created viewport. 3 SMG$CREATE_VIRTUAL_DISPLAY The Create Virtual Display routine creates a virtual display and returns its assigned display identifier. Format SMG$CREATE_VIRTUAL_DISPLAY number-of-rows ,number-of-columns ,display-id [,display-attributes] [,video-attributes] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments number-of-rows OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of rows in the newly created virtual display. The number-of-rows argument is the address of a signed longword that contains the desired number of rows. number-of-columns OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of columns in the newly created virtual display. The number-of-columns argument is the address of a signed longword that contains the desired number of columns. display-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the display-id of the newly created virtual display. The display-id argument is the address of an unsigned longword into which is written the display identifier. display-attributes OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Receives the current default display attributes. The optional display-attributes argument is the address of an unsigned longword into which the current display attributes are written. Valid values for display-attributes are as follows: SMG$M_BORDER Specifies a bordered display. If omitted, the display is not bordered. SMG$M_BLOCK_ Specifies a block-bordered display. If BORDER omitted, the display is not bordered. SMG$M_DISPLAY_ Specifies that control characters such as CONTROLS carriage return and line feed are displayed as graphic characters, if your terminal supports them. SMG$M_PROTECT_ Instructs the Screen Management Facility DISPLAY to return an error (SMG$_DSPIN_USE) if an SMG$ call is made from an AST routine that interrupted an SMG$ call on the same display. SMG$M_TRUNC_ICON Specifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred. video-attributes OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the default rendition to be applied to all output in this virtual display unless overridden by a call to a specific output routine (for example, SMG$CHANGE_RENDITION). The video- attributes argument is the address of an unsigned longword that contains the video attributes mask. Valid values for this argument are as follows: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video, that is, using the opposite of the default rendition of the virtual display. SMG$M_UNDERLINE Displays underlined characters. SMG$M_INVISIBLE Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set specifier. Valid values are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS. 3 SMG$CREATE_VIRTUAL_KEYBOARD The Create a Virtual Keyboard routine creates a virtual keyboard and returns its assigned keyboard identifier. Format SMG$CREATE_VIRTUAL_KEYBOARD keyboard-id [,input-device] [,default-filespec] [,resultant-filespec] [,recall-size] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the keyboard identifier of the newly created virtual keyboard. The keyboard-id argument is the address of an unsigned longword into which is written the keyboard identifier. input-device OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the file specification or logical name of the file or terminal to be used for this virtual keyboard. The input- device argument is the address of a descriptor pointing to the file specification. If omitted, this defaults to SYS$INPUT. default-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the default file specification. The default- filespec argument is the address of a descriptor pointing to the default file specification. If omitted, the null string is used. The default-filespec argument might be used to specify a default device and directory, leaving the input-device argument to supply the file name and type. resultant-filespec OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which the procedure writes the fully expanded file specification of the file used. The resultant-filespec argument is the address of a descriptor pointing to the string into which is written the file specification that was used. recall-size OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Number of input lines to be saved for later recall. The optional recall-size argument is the address of an unsigned byte containing the specified number of lines. A value of 0 turns off input line recall. By default, 20 lines are saved for later recall. 3 SMG$CURSOR_COLUMN The Return Cursor Column Position routine returns the virtual cursor's current column position in a specified virtual display. Format SMG$CURSOR_COLUMN display-id 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value SMG$CURSOR_COLUMN returns the current virtual cursor column position. 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference The display for which the column position is returned. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. 3 SMG$CURSOR_ROW The Return Cursor Row Position routine returns the virtual cursor's current row position in a specified virtual display. Format SMG$CURSOR_ROW display-id 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value SMG$CURSOR_ROW returns the current row position. 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference The display for which the row position is returned. The display- id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. 3 SMG$DEFINE_KEY The Perform a DEFINE/KEY Command routine performs the DEFINE/KEY command you provide. Format SMG$DEFINE_KEY key-table-id ,command-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifies the key definition table for which the DEFINE/KEY command is to be performed. The key-table-id argument is the address of an unsigned longword that contains the key table identifier. The key table identifier is returned by SMG$CREATE_KEY_TABLE. command-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the DEFINE/KEY command to be performed. The command-string argument is the address of a descriptor pointing to the command to be performed. The valid qualifiers for the DEFINE/KEY command are as follows: o /TERMINATE o /NOECHO o /LOCK o /IF_STATE o /SET_STATE The following two restrictions apply to the DEFINE/KEY qualifiers: o If you use the /LOCK qualifier, you must also use the /SET_ STATE qualifier. o If you use both the /SET_STATE and /TERMINATE qualifiers, you may not use /LOCK. 3 SMG$DELETE_CHARS The Delete Characters routine deletes characters in a virtual display. Format SMG$DELETE_CHARS display-id ,number-of-characters ,start-row ,start-column 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifies the virtual display from which characters are to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. number-of-characters OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of characters to be deleted. The number- of-characters argument is the address of a signed longword that contains the number of characters to be deleted. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row position at which to start the deletion. The start-row argument is the address of a signed longword that contains the row number at which to start the deletion. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column position at which to start the deletion. The start-column argument is the address of a signed longword that contains the column position at which to start the deletion. 3 SMG$DELETE_KEY_DEF The Delete Key Definition routine deletes a key definition from the specified table of key definitions. Format SMG$DELETE_KEY_DEF key-table-id ,key-name [,if-state] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifies the key table from which the key definition is deleted. The key-table-id argument is the address of an unsigned longword that contains the key table identifier. key-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the name of the key whose definition is to be deleted. The key-name argument is the address of a descriptor pointing to the key name. The key name is stripped of trailing blanks and converted to uppercase before use. if-state OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing a state name that further qualifies key-name. The if-state argument is the address of a descriptor pointing to the state name. If omitted, the null state is used. Thus if a key has several definitions depending on various values of if-state, this routine lets you delete only one of those definitions. 3 SMG$DELETE_LINE The Delete Line routine deletes lines from a virtual display. Format SMG$DELETE_LINE display-id ,start-row [,number-of-rows] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifies the virtual display from which lines are to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the first line to be deleted from the virtual display. The start-row argument is the address of a signed longword that contains the number of the first line to be deleted. number-of-rows OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of lines to be deleted. The number-of-rows argument is the address of a signed longword that contains the number of lines to be deleted. If omitted, one line is deleted. 3 SMG$DELETE_MENU The End Access to a Menu in the Virtual Display routine ends access to the menu choices in the specified virtual display. Format SMG$DELETE_MENU display-id [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display in which the menu choices are displayed. The display-id argument is the address of an unsigned longword containing this identifier. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask specifying possible actions to take when deleting the menu. The flags argument is the address of an unsigned longword that contains the flag. At this time, the only valid value is SMG$M_ERASE_MENU. If this option is specified, all rows containing menu items are erased. 3 SMG$DELETE_PASTEBOARD The Delete Pasteboard routine deletes a pasteboard. Format SMG$DELETE_PASTEBOARD pasteboard-id [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be deleted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask specifying whether the screen is cleared after the specified pasteboard is deleted. The flags argument is the address of an unsigned longword that contains the flag. Valid values are as follows: 0 Does not clear the screen. SMG$M_ERASE_PBD Clears the screen (default). SMG$M_IGNORE_ Deletes the pasteboard even if batching is in BATCHED effect. 3 SMG$DELETE_SUBPROCESS The Terminate a Subprocess routine deletes a subprocess that was created with the SMG$CREATE_SUBPROCESS routine. Format SMG$DELETE_SUBPROCESS display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display associated with the subprocess being deleted. The display-id argument is the address of an unsigned longword that contains this virtual display identifier. 3 SMG$DELETE_VIEWPORT The Delete a Viewport routine deletes the specified viewport from any pasteboards to which it is pasted. Format SMG$DELETE_VIEWPORT display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display associated with the viewport to be deleted. The display-id argument is the address of an unsigned longword containing the display identifier. 3 SMG$DELETE_VIRTUAL_DISPLAY The Delete Virtual Display routine deletes a virtual display. Format SMG$DELETE_VIRTUAL_DISPLAY display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier display-id is returned by SMG$CREATE_ VIRTUAL_DISPLAY. 3 SMG$DELETE_VIRTUAL_KEYBOARD The Delete Virtual Keyboard routine deletes a virtual keyboard. Format SMG$DELETE_VIRTUAL_KEYBOARD keyboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual keyboard to be deleted. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier. The keyboard identifier is returned by SMG$CREATE_VIRTUAL_ KEYBOARD. 3 SMG$DEL_TERM_TABLE The Delete Terminal Table routine terminates access to a private TERMTABLE.EXE and frees the associated virtual address space. Format SMG$DEL_TERM_TABLE 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments None. 3 SMG$DISABLE_BROADCAST_TRAPPING The Disable Broadcast Trapping routine disables trapping of broadcast messages for the specified terminal. Format SMG$DISABLE_BROADCAST_TRAPPING pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard for the terminal to be affected. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. 3 SMG$DISABLE_UNSOLICITED_INPUT The Disable Unsolicited Input routine disables the trapping of unsolicited input. Format SMG$DISABLE_UNSOLICITED_INPUT pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the keyboard (associated with the specified pasteboard) for which unsolicited input is being disabled. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. 3 SMG$DRAW_CHAR The Draw a Character in a Virtual Display routine draws a character at the specified position in a virtual display. Format SMG$DRAW_CHAR display-id ,flags [,row] [,column] [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display. The display-id argument is the address of an unsigned longword containing this identifier. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask indicating the character to be drawn. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following character values: o SMG$M_UP o SMG$M_DOWN o SMG$M_LEFT o SMG$M_RIGHT Note that you may perform a logical OR operation to draw T characters, corner characters, cross characters, and so forth. A value of 0 draws a diamond character. row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional row number specifying the row position at which the specified character is drawn. The row argument is the address of a signed longword containing the row number. If row is omitted, the character is drawn at the row position of the current virtual cursor. column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional column number specifying the column position at which the specified character is drawn. The column argument is the address of a signed longword containing the column number. If column is omitted, the character is drawn at the column position of the current virtual cursor. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$DRAW_LINE The Draw a Line routine draws a horizontal or vertical line. Format SMG$DRAW_LINE display-id ,start-row ,start-column ,end-row ,end-column [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display on which the line is to be drawn. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row at which to begin drawing the line. The start- row argument is the address of a signed longword that contains the row number at which to begin drawing the line. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which to begin drawing the line. The start-column argument is the address of a signed longword that contains the column number at which to begin drawing the line. end-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row at which the drawn line ends. The end-row argument is the address of a signed longword that contains the row number at which the drawn line ends. end-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which the drawn line ends. The end-column argument is the address of a signed longword that contains the column number at which the drawn line ends. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$DRAW_RECTANGLE The Draw a Rectangle routine draws a rectangle. Format SMG$DRAW_RECTANGLE display-id ,start-row ,start-column ,end-row ,end-column [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display on which the rectangle is to be drawn. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row number of the top left corner of the rectangle. The start-row argument is the address of a signed longword that contains the row number of the top left corner of the rectangle. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column number of the top left corner of the rectangle. The start-column argument is the address of a signed longword that contains the column number of the top left corner of the rectangle. end-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row number of the bottom right corner of the rectangle. The end-row argument is the address of a signed longword that contains the row number of the bottom right corner of the rectangle. end-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column number of the bottom right corner of the rectangle. The end-column argument is the address of a signed longword that contains the column number of the bottom right corner of the rectangle. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$ENABLE_UNSOLICITED_INPUT The Enable Unsolicited Input routine detects unsolicited input and calls an AST routine in response. Format SMG$ENABLE_UNSOLICITED_INPUT pasteboard-id ,AST-routine [,AST-argument] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard for which unsolicited input is being enabled. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_VIRTUAL_ PASTEBOARD. AST-routine OpenVMS usage:ast_procedure type: procedure value access: read only mechanism: by value AST routine to be called upon receipt of unsolicited input at the terminal. The AST-routine argument contains the routine's procedure value. SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited input and calls the AST routine with six arguments: the pasteboard-id, the AST-argument, R0, R1, PC, and PSL (on VAX systems) or PS (on Alpha systems). AST-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value A value to be passed to the AST routine. The AST-argument argument contains the value to be passed to the AST routine. 3 SMG$END_DISPLAY_UPDATE The End Display Update routine ends update batching for a virtual display. Format SMG$END_DISPLAY_UPDATE display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. 3 SMG$END_PASTEBOARD_UPDATE The End Pasteboard Update routine ends update batching for a pasteboard. Format SMG$END_PASTEBOARD_UPDATE pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard on which the batch count is to be decremented. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. If the batch count reaches 0, all buffered output for the specified pasteboard is written out. 3 SMG$ERASE_CHARS The Erase Characters routine erases characters in a virtual display by replacing them with blanks. Format SMG$ERASE_CHARS display-id ,number-of-characters ,start-row ,start-column 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display from which characters will be erased. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. number-of-characters OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of characters to be replaced with blanks. The number-of-characters argument is the address of a signed longword that contains the number of characters to be replaced with blanks. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row on which the erase operation begins. The start- row argument is the address of a signed longword that contains the number of the row at which the erasure is to begin. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column on which the erase operation begins. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure is to begin. 3 SMG$ERASE_COLUMN The Erase Column from Display routine erases the specified portion of the virtual display from the given position to the end of the column. Format SMG$ERASE_COLUMN display-id [,start-row] [,column-number] [,end-row] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display to be affected. The display-id argument is the address of an unsigned longword containing this virtual display identifier. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional line number at which the erase operation begins. The start-row argument is the address of a signed longword that contains the specified line number. If this argument is omitted, the column-number argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display. column-number OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional column number at which the erase operation begins. The column-number argument is the address of a signed longword that contains the specified column number. If this argument is omitted, the start-row argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display. end-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional row number at which the erase operation ends. The end- row argument is the address of a signed longword that contains the specified row number. 3 SMG$ERASE_DISPLAY The Erase Virtual Display routine erases all or part of a virtual display by replacing text characters with blanks. Format SMG$ERASE_DISPLAY display-id [,start-row] [,start-column] [,end-row] [,end-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be erased. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row at which the erase operation begins. The start- row argument is the address of a signed longword that contains the number of the row at which the erasure begins. If the start-row argument is not specified, start-column is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which the erase operation begins. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure begins. If the start-column argument is not specified, start-row is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased. end-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row at which the erase operation ends; that is, the last row to be erased. The end-row argument is the address of a signed longword that contains the number of the last row to be erased. If the end-row argument is not specified, end-column is also ignored and all remaining rows in the display are erased. end-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which the erase operation ends; that is, the last column to be erased. The end-column argument is the address of a signed longword that contains the number of the last column to be erased. If the end-column argument is not specified, end-row is also ignored and all remaining columns in the display are erased. 3 SMG$ERASE_LINE The Erase Line routine erases all or part of a line in a virtual display. Format SMG$ERASE_LINE display-id [,start-row] [,start-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the line at which the erase operation starts. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure starts. If omitted, start-column is also ignored and the current cursor position is used. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which the erase operation starts. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure starts. If omitted, start-row is also ignored and the current cursor position is used. 3 SMG$ERASE_PASTEBOARD The Erase Pasteboard routine erases the contents of a pasteboard. Format SMG$ERASE_PASTEBOARD pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be erased. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. 3 SMG$EXECUTE_COMMAND The Execute Command in a Subprocess routine executes the specified command in the subprocess created with the SMG$CREATE_ SUBPROCESS routine. Format SMG$EXECUTE_COMMAND display-id ,command-desc [,flags] [,ret-status] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier of the virtual display with which the subprocess is associated. The display-id argument is the address of an unsigned longword containing this identifier. command-desc OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Command string. The command-desc argument is the address of a descriptor pointing to the command string. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies optional behavior. The flags argument is the address of an unsigned longword that contains the flag. The valid values for flags are as follows: SMG$M_DATA_FOLLOWS Input data follows. The next call to SMG$EXECUTE_COMMAND contains input data for the currently executing command. Do not specify this value if this is the last input data item. If you do specify this value, ret-status is not returned. SMG$M_SEND_EOF Send end-of-file marker. The end-of-file marker is sent to the subprocess. ret-status OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by reference Optional status of the executed command, provided that the commands are not being buffered. The ret-status argument is the address of an unsigned longword containing this status. 3 SMG$FIND_CURSOR_DISPLAY The Find Display that Contains the Cursor routine returns the identifier of the most recently pasted virtual display that contains the physical cursor. Format SMG$FIND_CURSOR_DISPLAY pasteboard-id ,display-id [,pasteboard-row] [,pasteboard-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard in which the physical cursor is to be found. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. display-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the identifier of the display in which the physical cursor was found. The display-id argument is the address of an unsigned longword into which the display identifier is written. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference The row position at which to begin the search for the physical cursor. The optional pasteboard-row argument is the address of a signed longword containing the pasteboard row. You can use pasteboard-row instead of the physical cursor row. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference The column position at which to begin the search for the physical cursor. The optional pasteboard-column argument is the address of a signed longword containing the pasteboard column. You can use pasteboard-column instead of the physical cursor column. 3 SMG$FLUSH_BUFFER The Flush Buffer routine flushes all buffered output to the terminal. Format SMG$FLUSH_BUFFER pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be flushed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. 3 SMG$FLUSH_DISPLAY_UPDATE The Flush Display Update routine flushes any update batching to the screen and leaves the update batching in effect. Format SMG$FLUSH_DISPLAY_UPDATE display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display argument is returned by SMG$CREATE_VIRTUAL_DISPLAY. 3 SMG$GET_BROADCAST_MESSAGE The Get Broadcast Message routine determines whether a message has been broadcast to the pasteboard and returns the message. Format SMG$GET_BROADCAST_MESSAGE pasteboard-id [,message] [,message-length] [,message-type] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be checked for the presence of a broadcast message. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. message OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor A string that receives the broadcast message, if such a message is available. The message argument is the address of a descriptor that points to the string into which the message text is written. If this argument is omitted, the broadcast message is discarded. message-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Receives the actual length of the broadcast message. The message- length argument is the address of an unsigned word into which is written the length of the message. message-type OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Receives the type of broadcast message. The message-type argument is the address of an unsigned word into which is written the type of message. Values for message-type are defined by the $MSGDEF library definition. If the value for message-type is not MSG$_ TRMBRDCST, the condition value returned is SMG$_NOBRDMSG. 3 SMG$GET_CHAR_AT_PHYSICAL_CURSOR The Return Character at Cursor routine returns the character at the current physical cursor position. Format SMG$GET_CHAR_AT_PHYSICAL_CURSOR pasteboard-id ,character-code [,rendition] [,user-rendition] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard from which to retrieve the character. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. character-code OpenVMS usage:byte_unsigned type: byte (unsigned) access: write only mechanism: by reference Returned character code. The character-code argument is the address of an unsigned byte into which is written the character's ASCII code. rendition OpenVMS usage:byte_unsigned type: byte (unsigned) access: write only mechanism: by reference Receives the rendition code associated with the character code returned by the character-code argument. The rendition argument is the address of an unsigned byte into which is written the rendition code. user-rendition OpenVMS usage:byte_unsigned type: byte (unsigned) access: write only mechanism: by reference Receives the user rendition code associated with the character code returned by the character-code argument. The user-rendition argument is the address of an unsigned byte into which is written the user rendition code. 3 SMG$GET_DISPLAY_ATTR The Get Display Attributes routine receives the attributes associated with a virtual display. Format SMG$GET_DISPLAY_ATTR display-id [,height] [,width] [,display-attributes] [,video-attributes] [,character-set] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display for which information is requested. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. height OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the number of rows in the display. The optional height argument is the address of a signed longword into which the height is written. width OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the number of columns in the display. The optional width argument is the address of a signed longword into which is written the number of columns in the display. display-attributes OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Receives the current default display attributes. The optional display-attributes argument is the address of an unsigned longword into which the current display attributes are written. Valid values for display-attributes are as follows: SMG$M_BORDER Specifies a bordered display. If omitted, the display is not bordered. SMG$M_BLOCK_ Specifies a block bordered display. If BORDER omitted, the display is not bordered. SMG$M_DISPLAY_ Specifies that control characters such as CONTROLS carriage return and line feed are displayed as graphic characters, if your terminal supports them. SMG$M_TRUNC_ICON Specifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred. video-attributes OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Receives the current default video attributes. The optional video-attributes argument is the address of an unsigned longword into which the current video attributes are written. Valid video attributes are as follows: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_UNDERLINE Displays underlined characters. SMG$M_INVISIBLE Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Receives the default character set for all text in this virtual display. The optional character-set argument is the address of an unsigned longword that specifies the character set. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. flags OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Optional bit mask specifying attributes of the specified display. The flags argument is the address of an unsigned longword containing the flag. Valid values for flags are as follows: SMG$M_SUBPROCESS Display has a subprocess attached to it. SMG$M_MENU Display contains a menu. SMG$M_VIEWPORT Display contains a viewport. 3 SMG$GET_KEYBOARD_ATTRIBUTES The Get Keyboard Attributes routine gets information about a virtual keyboard and leaves it in a user-supplied area: the keyboard information table (KIT). Format SMG$GET_KEYBOARD_ATTRIBUTES keyboard-id ,keyboard-info-table ,keyboard-info-table-size 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the virtual keyboard from which to read. Create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_ KEYBOARD routine. keyboard-info-table OpenVMS usage:unspecified type: unspecified access: write only mechanism: by reference, array reference Receives the keyboard attributes. The keyboard-info-table argument is the address of a data block into which the keyboard attributes are written. The KIT is a byte block whose size and field references are described in $SMGDEF. It is the caller's responsibility to allocate the correct size block and to pass its address to this routine. The values in the keyboard-info-table can be accessed through the following symbolic names: SMG$L_DEV_CHAR Device characteristics (longword) SMG$L_DEV_DEPEND Specific characteristics 1 (longword) SMG$L_DEV_DEPEND2 Specific characteristics 2 (longword) SMG$L_DEV_DEPEND3 Specific characteristics 3 (longword) SMG$B_DEV_CLASS Device class (byte) - for example, DC$_TERM SMG$B_RECALL_NUM Size of recall buffer (byte)* SMG$B_DEVTYPE Physical device type (byte) - for example, TT$_VT100 SMG$B_TYPEAHD_ First character in type-ahead buffer (byte)* CHAR SMG$W_NUM_COLUMNS Terminal width (word) SMG$W_TYPEAHD_CNT Number of characters in type-ahead buffer (word)* Items marked with an asterisk (*) will be zero unless the device is a terminal (DEVCLASS = DC$_TERM). keyboard-info-table-size OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Size of the keyboard information table. The keyboard-info-table- size argument is the address of an unsigned longword containing the size of the KIT in bytes. The size you specify must be exact. You can specify this size with the symbolic constant SMG$C_KEYBOARD_INFO_BLOCK. 3 SMG$GET_KEY_DEF The Get Key Definition routine returns the key definition for a specified key. Format SMG$GET_KEY_DEF key-table-id ,key-name [,if-state] [,attributes] [,equivalence-string] [,state-string] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the key table from which you are extracting a definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier. The key table identifier is returned by SMG$CREATE_KEY_TABLE. key-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Specifies the name of the key associated with the definition. The key-name argument is the address of a descriptor pointing to the key name. if-state OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Specifies the current state name in effect after the key is pressed. The if-state argument is the address of a descriptor pointing to the state name. See SMG$ADD_KEY_DEF for more information. attributes OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Receives the attributes bit mask for this key definition. The attributes argument is the address of a longword into which is written the bit mask describing the key's attributes. Valid values are as follows: SMG$M_KEY_NOECHO If set, this bit specifies that equiv_string is not to be echoed when this key is pressed. If clear, equiv_string is echoed. If SMG$M_ KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored. SMG$M_KEY_ If set, this bit specifies that when this key TERMINATE is pressed (as qualified by if-state), the input line is complete and more characters should not be accepted. If clear, more characters may be accepted. SMG$M_KEY_ If set, and if state-string is specified, the LOCKSTATE state name specified by state-string remains at the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state-string remains in effect only for the next defined key stroke. SMG$M_KEY_ If set, this bit specifies that this key PROTECTED definition cannot be modified or deleted. If clear, the key definition can be modified or deleted. equivalence-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the equivalence string for this key definition. The equivalence-string argument is the address of a descriptor pointing to the string into which is written the equivalence string. state-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the new state name, if any, which is set by this key definition. The state-string argument is the address of a descriptor pointing to the string into which is written the new state string. 3 SMG$GET_NUMERIC_DATA The Get Numeric Terminal Data routine accesses TERMTABLE.EXE and returns the value associated with a specified Boolean or numeric capability. Format SMG$GET_NUMERIC_DATA termtable-address ,request-code ,buffer-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments termtable-address OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Specifies the address of the TERMTABLE entry for the desired terminal. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table (TERMTABLE). Before calling SMG$GET_NUMERIC_DATA, you must obtain this terminal table address by calling either SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE. request-code OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Request code that specifies the desired capability. The request- code argument is an unsigned longword constant containing this request code. The request code is of the form SMG$K_code, where code corresponds to a keyword in the terminal capabilities table (TERMTABLE), for example, ANSI_CRT. The SMG$K_code constants can be found in the library supplied by Compaq, $SMGTRMPTR. buffer-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Address of the first byte of the longword to which SMG$GET_ NUMERIC_DATA writes the numeric capability data. The buffer- address argument is an unsigned longword that contains the address of this buffer. 3 SMG$GET_PASTEBOARD_ATTRIBUTES The Get Pasteboard Attributes routine gets pasteboard attributes and stores them in the pasteboard information table. Format SMG$GET_PASTEBOARD_ATTRIBUTES pasteboard-id ,pasteboard-info-table ,pasteboard-info-table-size 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard for which information is requested. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. pasteboard-info-table OpenVMS usage:unspecified type: unspecified access: write only mechanism: by reference, array reference Receives the pasteboard attributes. The pasteboard-info-table argument is the address of a data structure into which are written the pasteboard attributes. The values in the pasteboard-info-table can be accessed through the following symbolic names: SMG$L_DEVCHAR Device characteristics (longword). SMG$L_DEVDEPEND Specific characteristics 1 (longword). SMG$L_ Specific characteristics 2 (longword). DEVDEPEND2 SMG$L_ Specific characteristics 3 (longword). DEVDEPEND3 SMG$B_DEVCLASS Device class (byte)-for example, DC$_TERM. SMG$B_SMG_ Internal SMG device type (byte). The four DEVTYPE possible values for SMG$B_SMG_DEVTYPE are as follows: SMG$K_UNKNOWN SMG$K_VTFOREIGN SMG$K_HARDCOPY SMG$K_VTTERMTABLE SMG$B_PHY_ Physical device type (byte)-for example, TT$_ DEVTYPE VT100. The possible values for SMG$B_PHY_DEVTYPE are defined in $TTDEF in STARLET. SMG$B_ROWS Number of rows on pasteboard (byte). SMG$W_WIDTH Pasteboard width (word). SMG$B_COLOR Background color setting (byte). Valid values for SMG$B_COLOR are as follows: SMG$C_COLOR_ Unknown background color UNKNOWN SMG$C_COLOR_WHITE Light background SMG$C_COLOR_BLACK Dark background SMG$C_COLOR_BLUE Blue background SMG$C_COLOR_CYAN Cyan (green-blue) background SMG$C_COLOR_GREEN Green background SMG$C_COLOR_ Magenta background MAGENTA SMG$C_COLOR_RED Red background SMG$C_COLOR_ Yellow background YELLOW SMG$C_COLOR_LIGHT White background SMG$C_COLOR_DARK Black background SMG$C_COLOR_USER1 User-defined background 1 SMG$C_COLOR_USER2 User-defined background 2 SMG$B_PARITY Parity attributes (byte)-this field is zero if the pasteboard is not a terminal. SMG$W_SPEED Terminal speed (word)-this field is zero if the pasteboard is not a terminal. SMG$W_FILL Fill characteristics (word)-this field is zero if the pasteboard is not a terminal. SMG$W_PHYS_ Pasteboard row containing physical cursor CURSOR_ROW (word). SMG$W_PHYS_ Pasteboard column containing physical cursor CURSOR_COL (word). SMG$L_CURSOR_ Display identifier of topmost display containing DID physical cursor (longword). pasteboard-info-table-size OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the number of bytes in the pasteboard information table. The pasteboard-info-table-size argument is the address of an unsigned longword that contains the size (in bytes) of the pasteboard information table. The size you specify must be exact. You can specify this size with the symbolic constant SMG$C_PASTEBOARD_INFO_BLOCK. 3 SMG$GET_PASTING_INFO Provided that the specified virtual display is currently pasted, the Return Pasting Information routine returns the row and column of the pasting. Format SMG$GET_PASTING_INFO display-id ,pasteboard-id ,flags [,pasteboard-row] [,pasteboard-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display to be examined. The display-id argument is the address of an unsigned longword containing the identifier of this virtual display. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard. flags OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Bit mask indicating the status of the specified virtual display with respect to the specified pasteboard. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows: 0 The virtual display is not pasted to the specified pasteboard. SMG$M_DISPLAY_ The virtual display specified by display-id PASTED is pasted to the pasteboard specified by the pasteboard-id argument. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display. 3 SMG$GET_TERM_DATA The Get Terminal Data routine accesses TERMTABLE.EXE and returns the character sequence that causes a terminal to perform a specified operation. Format SMG$GET_TERM_DATA termtable-address ,request-code ,maximum-buffer-length ,return-length ,capability-data [,input-argument-vector] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments termtable-address OpenVMS usage:address type: longword (unsigned) access: read only mechanism: by reference Specifies the address of the TERMTABLE entry for the desired terminal. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table (TERMTABLE). The TERMTABLE address is returned by SMG$INIT_TERM_TABLE or SMG$INIT_TERM_TABLE_BY_TYPE. request-code OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Longword constant of the form SMG$K_code, where code is the name of the desired capability field. The request-code argument is the address of a signed longword that contains the request code. The SMG$K_code constants can be found in the library supplied by Compaq, $SMGTRMPTR. maximum-buffer-length OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Maximum length of the buffer into which the requested capability data is written. The maximum-buffer-length argument is the address of a signed longword that contains the maximum number of bytes that can be written into the buffer. return-length OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the number of bytes actually written into the buffer. The return-length argument is the address of a signed longword into which is written the number of bytes transferred into the buffer. capability-data OpenVMS usage:unspecified type: unspecified access: by reference, array reference mechanism: 0 Address of the first byte of the buffer which is to receive the capability data. The capability-data argument contains the address of the buffer. input-argument-vector OpenVMS usage:vector_longword_unsigned type: longword (unsigned) access: read only mechanism: by reference, array reference Address of a list of longwords used for capabilities that require a variable number of arguments, and for those that require substitution or arithmetic operations on an argument. The input- argument-vector argument is the address of an array of unsigned longwords that contains capability arguments. The first longword must contain the number of arguments that follow. 3 SMG$GET_VIEWPORT_CHAR The Get Characteristics of Display Viewport routine returns the characteristics of the specified viewport. Format SMG$GET_VIEWPORT_CHAR display-id [,viewport-row-start] [,viewport-column-start] [,viewport-number-rows] [,viewport-number-columns] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display associated with the viewport. The display-id argument is the address of an unsigned longword containing this identifier. viewport-row-start OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Optional argument that receives the starting row number of the viewport. The viewport-row-start argument is the address of a signed longword that receives this row number. viewport-column-start OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Optional argument that receives the starting column number of the specified viewport. The viewport-column-start argument is the address of a signed longword that receives this column number. viewport-number-rows OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Optional argument that receives the number of rows in the specified viewport. The viewport-number-rows argument is the address of a signed longword that receives this number. viewport-number-columns OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Optional argument that receives the number of columns in the specified viewport. The viewport-number-columns argument is the address of a signed longword that receives this number. 3 SMG$HOME_CURSOR The Home Cursor routine moves the virtual cursor to the specified corner of a virtual display. Format SMG$HOME_CURSOR display-id [,position-code] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display in which the virtual cursor is moved. The display-id argument is the address of a longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. position-code OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the point to which the virtual cursor moves. The position-code argument is the address of a longword that contains the position code. Valid codes for position-code are as follows: Code Meaning SMG$C_UPPER_LEFT Row 1, column 1 (the upper left corner). This is the default if position-code is not specified. SMG$C_LOWER_LEFT Row n, column 1 (where n is the number of rows in the display). That is, the lower left corner. It is useful to specify this position when accepting input for an upward-scrolling virtual display. SMG$C_UPPER_RIGHT Row 1, column m (where m is the number of columns in the display). That is, the upper right corner. SMG$C_LOWER_RIGHT Row n, column m (where n is the number of rows and m is the number of columns in the display). That is, the lower right corner. 3 SMG$INIT_TERM_TABLE The Initialize Terminal Table routine initializes the TERMTABLE database for the terminal named, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that terminal. Format SMG$INIT_TERM_TABLE terminal-name, termtable-address 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments terminal-name OpenVMS usage:device_name type: character string access: read only mechanism: by descriptor Specifies the name of the terminal. The terminal-name argument is the address of a descriptor pointing to the terminal name. The name must be an entry in TERMTABLE.EXE. termtable-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Address of the entry for a particular type of terminal in TERMTABLE.EXE. The termtable-address argument is the address of an unsigned longword that contains the address of the terminal capabilities table. You use this address when calling the SMG$GET_TERM_DATA procedure for the specified type of terminal. The TERMTABLE address is also returned by SMG$INIT_TERM_TABLE_BY_TYPE. 3 SMG$INIT_TERM_TABLE_BY_TYPE The Initialize TERMTABLE by OpenVMS Terminal Type routine initializes the TERMTABLE database for the terminal named, so that subsequent calls to SMG$GET_TERM_DATA can extract information and command strings for that terminal. Format SMG$INIT_TERM_TABLE_BY_TYPE terminal-type ,termtable-address [,terminal-name] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments terminal-type OpenVMS usage:byte_signed type: byte (signed) access: read only mechanism: by reference The device type of the terminal, as designated by an OpenVMS symbolic terminal type or by another value returned by the $GETDVI system service. The terminal-type argument is the address of a signed byte that contains the terminal type. termtable-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference Address of the entry for a particular type of terminal in TERMTABLE.EXE. The termtable-address argument is the address of an unsigned longword into which is written the address of a terminal entry. Use this address when calling the SMG$GET_TERM_DATA procedure for the specified type of terminal. terminal-name OpenVMS usage:device_name type: character string access: write only mechanism: by descriptor A string into which is written the terminal name associated with the device type. The terminal-name argument is the address of a descriptor pointing to the string into which the terminal name is written. 3 SMG$INSERT_CHARS The Insert Characters routine inserts characters into a virtual display. Format SMG$INSERT_CHARS display-id ,character-string ,start-row ,start-column [,rendition-set] [,rendition-complement] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. character-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor The character string to be inserted. The character-string argument is the address of a descriptor that points to the string to be inserted. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference The row position at which to begin the insertion. The start-row argument is the address of a signed longword that contains the row number. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference The column position at which to begin the insertion. The start- column argument is the address of a signed longword that contains the column number. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. 3 SMG$INSERT_LINE The Insert Line routine inserts a line into a virtual display and scrolls the display. Format SMG$INSERT_LINE display-id ,start-row [,character-string] [,direction] [,rendition-set] [,rendition-complement] [,flags] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row number at which the string is inserted and at which scrolling begins. The start-row argument is the address of a signed longword that contains the row number. character-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor The character string to be inserted by SMG$INSERT_LINE. The character-string argument is the address of a descriptor pointing to this string. direction OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the scrolling direction. The direction argument is the address of a longword bit mask that contains the direction code. Valid values are SMG$M_UP and SMG$M_DOWN. SMG$M_UP is the default. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to take if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows: 0 Does not wrap (the default) SMG$M_WRAP_CHAR Wraps at the last character on the line SMG$M_WRAP_WORD Wraps at the last space on the line character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. 3 SMG$INVALIDATE_DISPLAY The Mark a Display as Invalid routine marks a display as invalid and causes the entire display to be redrawn. Format SMG$INVALIDATE_DISPLAY display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. 3 SMG$KEYCODE_TO_NAME The Translate a Key Code into a Key Name routine translates the key code of a key on the keyboard into its associated key name. Format SMG$KEYCODE_TO_NAME key-code ,key-name 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-code OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Specifies the key code to translate into a key name. The key-code argument is the address of an unsigned word that contains the key code. The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_ KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word- terminator-code argument. key-name OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String containing the name of the key into which key-code is to be translated. The key-name argument is the address of a descriptor pointing to the character string containing the key name. The key-name argument is simply the name of the key (for example, COMMA, PERIOD, KP4, and so forth). 3 SMG$LABEL_BORDER The Label a Virtual Display Border routine supplies a label for a virtual display's border. Format SMG$LABEL_BORDER display-id [,text] [,position-code] [,units] [,rendition-set] [,rendition-complement] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor The new label for this display's border. The text argument is the address of a descriptor pointing to the label text. If this string is supplied, it replaces the current label text for this border. If omitted, the display is not labeled. position-code OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies which of the display's borders contains the label. The position-code argument is the address of an unsigned longword that contains the position code. Valid positions are as follows: o SMG$K_TOP o SMG$K_BOTTOM o SMG$K_RIGHT o SMG$K_LEFT If this argument is omitted, the label is displayed on the top border. units OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the character position at which the label begins within the border. The units argument is the address of a signed longword that contains the character position. If omitted, the label is centered in the specified border. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. 3 SMG$LIST_KEY_DEFS The List Key Definitions routine returns, one at a time, the definitions (equivalence strings) associated with specified keys in a specified key definition table. Format SMG$LIST_KEY_DEFS key-table-id ,context [,key-name] [,if-state] [,attributes] [,equivalence-string] [,state-string] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the key definition table from which you are extracting a key definition. The key-table-id argument is the address of an unsigned longword that contains the key table identifier. The key definition table identifier is returned by SMG$CREATE_ KEY_TABLE. context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Provides a means to extract a series of key definitions from a key definition table. The context argument is the address of an unsigned longword that contains the context variable. For the first call to this routine, you should set the context argument to zero. The context argument is incremented by the SMG$LIST_KEY_DEFS routine so that the next call returns the next key definition. key-name OpenVMS usage:char_string type: character string access: modify mechanism: by descriptor Identifies the key whose value you are listing. The key-name argument is the address of a descriptor pointing to the key name. if-state OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the state name which qualifies the next definition in the key definition table. The if-state argument is the address of a descriptor pointing to the string into which the state name is written. attributes OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Attributes of this key definition. The attributes argument is the address of an unsigned longword into which the key attributes are written. Possible attributes are as follows: SMG$M_KEY_NOECHO If set, this bit specifies that equiv_string is not to be echoed when this key is pressed; if clear, equiv_string is echoed. If SMG$M_ KEY_TERMINATE is not set, SMG$M_KEY_NOECHO is ignored. SMG$M_KEY_ If set, this bit specifies that when this key TERMINATE is pressed (as qualified by if-state), the input line is complete and more characters should not be accepted. If clear, more characters may be accepted. SMG$M_KEY_ If set, and if state-string is specified, the LOCKSTATE state name specified by state-string remains at the current state until explicitly changed by a subsequent keystroke whose definition includes a state-string. If clear, the state name specified by state-string remains in effect only for the next defined keystroke. SMG$M_KEY_ If set, this bit specifies that this key PROTECTED definition cannot be modified or deleted. If clear, the key definition can be modified or deleted. equivalence-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor The character string into which the equivalence string is written for the next key definition. The equivalence-string argument is the address of a descriptor pointing to the string into which equivalence-string is written. state-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor A string into which is written the new state name, if any, set by the next key definition. The state-string argument is the address of a descriptor pointing to the string into which the state name is written. If this key definition sets a state, the attributes flag SMG$M_KEY_SETSTATE is also set. 3 SMG$LIST_PASTEBOARD_ORDER The Return Pasting Information routine returns the pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual display are also returned. Format SMG$LIST_PASTEBOARD_ORDER display-id ,context ,pasteboard-id [,pasteboard-row] [,pasteboard-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier of the virtual display that is pasted. The display-id argument is the address of an unsigned longword containing the identifier of this display. context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context to search. The context argument is the address of an unsigned longword containing this context. On the initial call, you should set context to zero. SMG$LIST_PASTEBOARD_ORDER updates the value of context. The updated value should then be passed on the subsequent calls to obtain the next pasted display identifier. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display. 3 SMG$LIST_PASTING_ORDER The Return Virtual Display Pasting Information routine returns the identifiers of the virtual displays pasted to a specified pasteboard. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned. Format SMG$LIST_PASTING_ORDER pasteboard-id ,context ,display-id [,pasteboard-row] [,pasteboard-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard. context OpenVMS usage:context type: longword (unsigned) access: modify mechanism: by reference Context to search. The context argument is the address of an unsigned longword containing this context. On the initial call, you should set context to zero. SMG$LIST_PASTING_ORDER updates the value of context. The updated value should then be passed on subsequent calls to obtain the next pasted display identifier. display-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Identifier of the virtual display that is pasted. The display-id argument is the address of an unsigned longword containing the identifier of this virtual display. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display. 3 SMG$LOAD_KEY_DEFS The Load Key Definitions routine loads a file of key definitions (DEFINE/KEY commands) into a specified key table. Format SMG$LOAD_KEY_DEFS key-table-id ,filespec [,default-filespec] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the key table into which you are loading key definitions. The key-table-id argument is the address of an unsigned longword that contains the key table identifier. The key table identifier is returned by SMG$CREATE_KEY_TABLE. filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the file specification for the file of DEFINE/KEY commands. The filespec argument is the address of a descriptor pointing to the file specification. default-filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the default file specification for the file of DEFINE/KEY commands. The default-filespec argument is the address of a descriptor pointing to the default file specification. If omitted, the null string is used. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies whether filespec is to be treated as a logical name. The flags argument is the address of an unsigned longword that contains the flag. If set, flags specifies that filespec should be translated, but if this is not possible, that the null string be used. 3 SMG$LOAD_VIRTUAL_DISPLAY The Load a Virtual Display from a File routine creates a new virtual display and loads it with a virtual display saved with SMG$SAVE_VIRTUAL_DISPLAY. Format SMG$LOAD_VIRTUAL_DISPLAY display-id [,filespec] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Identifier of the new virtual display to be loaded with the saved virtual display. The display-id argument is the address of an unsigned longword into which is written the new display identifier. filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the file specification of the file in which the specified virtual display is saved. The filespec argument is a character string containing the file specification. If filespec is omitted, SMG$LOAD_VIRTUAL_DISPLAY searches for the default file specification SMGDISPLY.DAT. 3 SMG$MOVE_TEXT The Move Text from One Virtual Display to Another routine moves a rectangle of text from one virtual display to another virtual display. Given two points in opposite corners of the rectangle, SMG$MOVE_TEXT determines the desired width and height of the new virtual display. Format SMG$MOVE_TEXT display-id ,top-left-row ,top-left-column ,bottom-right-row ,bottom-right-column ,display-id2 [,top-left-row2] [,top-left-column2] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display from which text is to be moved. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. top-left-row OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Top left row of the rectangle of text you want to move. The top-left-row argument is the address of an unsigned longword containing the row number. top-left-column OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Top left column of the rectangle of text you want to move. The top-left-column argument is the address of an unsigned longword containing the column number. bottom-right-row OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Bottom right row of the rectangle of text you want to move. The bottom-right-row argument is the address of an unsigned longword containing the row number. bottom-right-column OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Bottom right column of the rectangle of text you want to move. The bottom-right-column argument is the address of an unsigned longword containing the column number. display-id2 OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to which the text is to be moved. The display-id2 argument is the address of an unsigned longword that contains the display identifier. The display identifier display-id2 is returned by SMG$CREATE_ VIRTUAL_DISPLAY. top-left-row2 OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Top left row of the rectangle that is the destination of the text you want to move. The optional top-left-row2 argument is the address of an unsigned longword containing the row number. If you do not specify a value for top-left-row2, the text is moved to the current virtual cursor row. top-left-column2 OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Top left column of the rectangle that is the destination of the text you want to move. The optional top-left-column2 argument is the address of an unsigned longword containing the column number. If you do not specify a value for top-left-column2, the text is moved to the current virtual cursor column. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to take when moving the specified text. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values: SMG$M_TEXT_SAVE Does not erase the text after moving. SMG$M_TEXT_ONLY Moves the text but not the attributes. 3 SMG$MOVE_VIRTUAL_DISPLAY The Move Virtual Display routine relocates a virtual display on a pasteboard and preserves the pasting order. Format SMG$MOVE_VIRTUAL_DISPLAY display-id ,pasteboard-id ,pasteboard-row ,pasteboard-column [,top-display-id] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be moved. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard on which the movement is to take place. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row of the pasteboard that is to contain row 1 of the new location of the specified virtual display. The pasteboard-row argument is the address of a signed longword that contains the row number. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column of the pasteboard that is to contain column 1 of the specified virtual display. The pasteboard-column argument is the address of a signed longword that contains the column number. top-display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display under which the moving display- id will be pasted. The top-display-id argument is the address of an unsigned longword containing the specified virtual display identifier. Note that the use of the top-display-id argument is only valid when the virtual display specified by display-id is not currently pasted and the virtual display specified by top-display-id is pasted. 3 SMG$NAME_TO_KEYCODE The Translate a Key Name into a Key Code routine translates the key name of a key on the keyboard into its associated key code. Format SMG$NAME_TO_KEYCODE key-name ,key-code 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the name of the key to be translated into a key code. The key-name argument is the address of a descriptor pointing to the character string containing the key name. The key-name argument is simply the name of the key (for example, COMMA, PERIOD, KP4, and so forth). key-code OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Specifies the key code into which key-name is to be translated. The key-code argument is the address of an unsigned word that contains the key code. The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_ KEYSTROKE, SMG$READ_STRING, and SMG$READ_VERIFY in the word- terminator-code argument. 3 SMG$PASTE_VIRTUAL_DISPLAY The Paste Virtual Display routine pastes a virtual display to a pasteboard. Format SMG$PASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id [,pasteboard-row] [,pasteboard-column] [,top-display-id] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be pasted. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to which the display is to be pasted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row of the pasteboard that is to contain row 1 of the specified virtual display. The pasteboard-row argument is the address of a signed longword that contains the row number. If pasteboard-row is omitted, the last row to which the virtual display was pasted (on any pasteboard) is used. If pasteboard-row is omitted and the virtual display was not previously pasted, then row 1 is used. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column of the pasteboard that is to contain column 1 of the specified virtual display. The pasteboard-column argument is the address of a signed longword that contains the column number. If pasteboard-column is omitted, the last column to which the virtual display was pasted (on any pasteboard) is used. If pasteboard-column is omitted and the virtual display was not previously pasted, then column 1 is used. top-display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display under which to paste display- id. The optional top-display-id argument is the address of an unsigned longword containing this identifier. Note that the virtual display specified by top-display-id must already be pasted. 3 SMG$POP_VIRTUAL_DISPLAY The Delete a Series of Virtual Displays routine deletes a specified virtual display and all displays that were pasted on the specified pasteboard on top of the specified virtual display. Format SMG$POP_VIRTUAL_DISPLAY display-id ,pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the lowest (first) virtual display to be deleted. The display-id argument is the address of an unsigned longword that contains the display identifier. All displays that are higher in the pasting order (that is, all displays that were pasted after the specified display) are deleted as well. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard on which the display deletions take place. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. 3 SMG$PRINT_PASTEBOARD The Print Pasteboard Using a Print Queue routine prints the contents of the specified pasteboard on a line printer. Format SMG$PRINT_PASTEBOARD pasteboard-id [,queue-name] [,copies] [,form-name] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the pasteboard to be printed. The pasteboard-id argument is the address of an unsigned longword containing this identifier. queue-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional queue name. The queue-name argument is the address of a descriptor pointing to the queue name in which to enter the file. The default is SYS$PRINT. copies OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional number of copies to print. The copies argument is the address of a signed longword containing this number. The default and minimum is one copy. form-name OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional name of the form to use when printing. The form-name argument is the address of a descriptor pointing to the form name. The default is "DEFAULT". 3 SMG$PUT_CHARS The Write Characters to a Virtual Display routine writes characters in a virtual display with the text you specify. Format SMG$PUT_CHARS display-id ,text [,start-row] [,start-column] [,flags] [,rendition-set] [,rendition-complement] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the character string. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row at which output begins. If start-row is omitted, output begins on the current row. The start-row argument is the address of a signed longword that contains the row number. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which output begins. If start-column is omitted, output begins on the current column. The start-column argument is the address of a signed longword that contains the column number. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to take before the specified text is output. The flags argument is the address of an unsigned longword bit mask that contains the flag. The flags argument accepts the following values: 0 Does not erase line (the default). SMG$M_ERASE_TO_ Erases the remaining part of the line. EOL SMG$M_ERASE_LINE Erases the entire line. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. 3 SMG$PUT_CHARS_HIGHWIDE The Write Double-Height Double-Width Characters routine writes double-height, double-width (highwide) characters to a virtual display. Format SMG$PUT_CHARS_HIGHWIDE display-id ,text [,start-row] [,start-column] [,rendition-set] [,rendition-complement] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the text. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the line at which output begins. The start-row argument is the address of a signed longword that contains the line number. If start-row is omitted or if it is equal to zero, output begins on the current line. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which output begins. The start-column argument is the address of a signed longword that contains the column number. If start-column is omitted or if it is equal to zero, output begins on the current column. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. 3 SMG$PUT_CHARS_MULTI The Put Text with Multiple Renditions to Display routine writes text with multiple renditions to the virtual display. Format SMG$PUT_CHARS_MULTI display-id ,text [,start-row] [,start-column] [,flags] [,rendition-string] [,rendition-complement] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains this identifier. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Text to be output. The text argument is the address of a descriptor pointing to the output string. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional row number at which to start output. The start-row argument is the address of a signed longword containing this number. If omitted, the current row number is used. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional column number at which to start output. The start-column argument is the address of a signed longword containing this number. If omitted, the current column number is used. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to take before the specified text is output. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values: 0 Does not erase line (the default). SMG$M_ERASE_TO_ Erases the remaining part of the line. EOL SMG$M_ERASE_LINE Erases the entire line. rendition-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional bit mask string that controls the video attributes. The rendition-string argument is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be set for the corresponding byte in the text string in the display. The following attributes can be specified for each byte using the rendition-string argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. rendition-complement OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional bit mask string that controls the video attributes. The rendition-complement is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be complemented for the corresponding byte in the text string in the display. If the same bit in the same byte is specified in both the rendition-string and rendition-complement arguments, rendition- string is evaluated first, followed by rendition-complement. By using these two parameters together, you can independently control each attribute in a single routine call. On a single- attribute basis, you can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. 3 SMG$PUT_CHARS_WIDE The Write Double-Width Characters routine writes double-width characters to a virtual display. Format SMG$PUT_CHARS_WIDE display-id ,text [,start-row] [,start-column] [,rendition-set] [,rendition-complement] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the text. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the line at which output begins. The start-row argument is the address of a signed longword that contains the line number. If start-row is omitted, output begins on the current line. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which output begins. If start-column is omitted, output begins on the current column. The start-column argument is the address of a signed longword that contains the column number. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off character-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS. 3 SMG$PUT_HELP_TEXT The Output Help Text to the Display routine retrieves and outputs the help text for the specified topic in the virtual display provided. Format SMG$PUT_HELP_TEXT display-id [,keyboard-id] [,help-topic] [,help-library] [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier of the virtual display to which the help text is written. The display-id argument is the address of an unsigned longword that contains this virtual display identifier. Note that this display must be pasted and cannot be occluded or batched. keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Optional keyboard identifier of the virtual keyboard used for input. The keyboard-id argument is the address of an unsigned longword that contains this virtual keyboard identifier. If the keyboard-id parameter is not specified, prompting is disabled. help-topic OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional help topic. The help-topic argument is the address of a descriptor pointing to the help topic string. help-library OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional help library name. The help-library argument is the address of a descriptor pointing to the help library name. The default is SYS$HELP:HELPLIB.HLB. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$PUT_LINE The Write Line to Virtual Display routine writes a line of text to a virtual display, beginning at the current virtual cursor position. Format SMG$PUT_LINE display-id ,text [,line-advance] [,rendition-set] [,rendition-complement] [,flags] [,character-set] [,direction] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor The characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the text. line-advance OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of lines to advance after output. The line-advance argument is the address of a signed longword that contains the number of lines to advance. The default is 1. If you specify 0 for line-advance, SMG$PUT_LINE overwrites any existing text. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to be taken if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values: 0 Does not wrap (default). SMG$M_WRAP_CHAR Wraps at the last character on the line. SMG$M_WRAP_WORD Wraps at the last space on the line. character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (default) and SMG$C_SPEC_GRAPHICS. direction OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the direction to scroll, if scrolling is necessary. The direction argument is the address of a longword bit mask that contains the direction code. Valid values are SMG$M_UP (default) and SMG$M_DOWN. 3 SMG$PUT_LINE_HIGHWIDE The Write Double-Height and Double-Width Line routine writes a line of text with double-height and double-width (highwide) characters. Format SMG$PUT_LINE_HIGHWIDE display-id ,text [,line-advance] [,rendition-set] [,rendition-complement] [,flags] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier. The display-id argument is the address of an unsigned longword that contains the display identifier of the virtual display. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Text to be output. The text argument is the address of the descriptor pointing to the output string. line-advance OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of lines to advance. The line-advance argument is the address of a signed longword that contains the number of lines to advance after the output. This argument is optional. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to be taken if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values: 0 Does not wrap (default). SMG$M_WRAP_CHAR Wraps at the last character on the line. SMG$M_WRAP_WORD Wraps at the last space on the line. character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (default), and SMG$C_SPEC_GRAPHICS. 3 SMG$PUT_LINE_MULTI The Write Line with Multiple Renditions to Display routine writes lines with multiple renditions to the virtual display, optionally followed by cursor movement sequences. Format SMG$PUT_LINE_MULTI display-id ,text ,rendition-string [,rendition-complement] [,line-advance] [,flags] [,direction] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display to be affected. The display-id argument is the address of an unsigned longword that contains this identifier. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Text to be output. The text argument is the address of a descriptor pointing to the output string. rendition-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional bit mask string that controls the video attributes. The rendition-string argument is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be set for the corresponding byte in the text string in the display. The following attributes can be specified for each byte using the rendition-string argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. rendition-complement OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional bit mask string that controls the video attributes. The rendition-complement is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be complemented for the corresponding byte in the text string in the display. If the same bit in the same byte is specified in both the rendition-string and rendition-complement arguments, rendition- string is evaluated first, followed by rendition-complement. By using these two parameters together, you can independently control each attribute in a single routine call. On a single- attribute basis, you can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off line-advance OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional number of lines to advance after output. The line- advance argument is the address of a signed longword containing this number. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to take if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values: 0 Does not wrap (default). SMG$M_WRAP_CHAR Wraps at the last character on the line. SMG$M_WRAP_WORD Wraps at the last space on the line. direction OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Optional direction specifier. The direction argument is the address of an unsigned longword that contains the direction code specifying the scrolling direction, if scrolling is necessary. Valid values are SMG$M_UP (default) and SMG$M_DOWN. character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (default) and SMG$C_SPEC_GRAPHICS. 3 SMG$PUT_LINE_WIDE The Write Double-Width Line routine writes a line of double-width text to a virtual display. Format SMG$PUT_LINE_WIDE display-id ,text [,line-advance] [,rendition-set] [,rendition-complement] [,flags] [,character-set] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display affected. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the text. line-advance OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of lines to advance after output. The line- advance argument is the address of a signed longword integer that contains the number of lines to advance. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies the action to take if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values: 0 Does not wrap (default). SMG$M_WRAP_CHAR Wraps at the last character on the line. SMG$M_WRAP_WORD Wraps at the last space on the line. character-set OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set code. Valid values are SMG$C_ASCII (default), and SMG$C_SPEC_GRAPHICS. 3 SMG$PUT_PASTEBOARD The Output Pasteboard Using Routine routine accesses the contents of a pasteboard. Format SMG$PUT_PASTEBOARD pasteboard-id ,action-routine [,user-argument] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Pasteboard identifier. The pasteboard-id argument is the address of an unsigned longword containing the pasteboard identifier. action-routine OpenVMS usage:procedure type: procedure value access: read only mechanism: by value Pasteboard routine to be called. The action-routine argument is the address of the routine's procedure value. Because SMG$ cannot determine the resulting type of device, device-independent characters (plus sign [+], vertical bar [|]) are used to draw lines. The action-routine accepts two arguments: o A pointer to a string descriptor describing the line in the pasteboard. o The user argument, or 0, passed by value. The action routine should return a success status (low bit set) as a return value, otherwise SMG$PUT_PASTEBOARD will terminate, and the status value will be returned as the return value for SMG$PUT_PASTEBOARD. user-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value The argument you supply to the action-routine. The user-argument argument is an unsigned longword that contains the value to be passed to the action routine. If user-argument is omitted, a 0 will be passed as the user argument. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies whether a form feed is passed to the action routine. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows: 0 No form-feed line is sent. SMG$M_FORM_FEED The first line passed to the action routine is a form feed. 3 SMG$PUT_STATUS_LINE The Output Line of Text to Hardware Status Line routine outputs a line of text to the hardware status line. Format SMG$PUT_STATUS_LINE pasteboard-id ,text 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard containing the hardware status line. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. text OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor The characters to be written to the hardware status line. The text argument is the address of a descriptor pointing to the text. 3 SMG$READ_COMPOSED_LINE The Read Composed Line routine reads a line of input composed of normal keystrokes and equivalence strings. Format SMG$READ_COMPOSED_LINE keyboard-id [,key-table-id] ,resultant-string [,prompt-string] [,resultant-length] [,display-id] [,flags] [,initial-string] [,timeout] [,rendition-set] [,rendition-complement] [,word-terminator-code] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual keyboard from which input is to be read. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier. The keyboard identifier is returned by SMG$CREATE_VIRTUAL_ KEYBOARD. key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the key definition table to be used for translating keystrokes. The key-table-id argument is the address of an unsigned longword that contains the key definition table identifier. The key definition table identifier is returned by SMG$CREATE_ KEY_TABLE. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which SMG$READ_COMPOSED_LINE writes the complete composed line. The resultant-string argument is the address of a descriptor pointing to the string in which the composed line is written. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String used to prompt for the read operation. The prompt-string argument is the address of a descriptor pointing to the prompt string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Receives the number of characters read or the maximum length of resultant-string, whichever is less. The resultant-length argument is the address of an unsigned longword into which SMG$READ_COMPOSED_LINE writes the number of characters read. display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier. The display-id argument is the address of an unsigned longword that contains the display identifier. This argument is optional only if you are not using the Screen Management Facility's output routines. If you are using the Screen Management Facility input and output routines, this argument specifies the virtual display in which the input is to occur. The virtual display specified must be pasted to the same pasteboard as specified by keyboard-id and must not be occluded. You cannot accept input from an occluded area of the virtual display. In the case of multiple virtual displays, each virtual display has an associated virtual cursor position. At the same time, there is a single physical cursor position corresponding to the current location of the physical cursor. If the display-id argument is specified, the read begins at the current virtual cursor position in the specified virtual display. If the display identifier is omitted, the read begins in the current physical cursor position. The length of the prompt-string plus the key entered is limited to the number of visible columns in the display. NOTE This virtual display must be pasted in column 1 and may not have any other virtual displays to its right. This restriction is necessary because otherwise any occurrence of Ctrl/R or Ctrl/U would blank out the entire line, including any output pasted to the right. To circumvent this restriction, you can use SMG$REPAINT_LINE whenever a Ctrl/R or Ctrl/U is encountered. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies enabled keys. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows: 0 Line editing is enabled and function keys (F6 to F14) cannot be used. SMG$M_FUNC_KEYS Function keys (F6 to F14) may be used and line editing is disabled. SMG$M_NOKEEP Lines entered in the recall buffer are not saved. SMG$M_NORECALL Line recall is disabled for this I/O only. Because the OpenVMS terminal driver uses the function keys (F6 to F14) for line editing on some terminals, you cannot have function keys and line editing enabled at the same time. initial-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional string that contains the initial characters of the field. The initial-string argument is the address of a descriptor pointing to the string. The string is written to the display in the input area, as if it had been entered from the keyboard. It may be edited in the usual way (provided that the SMG$M_FUNC_KEYS flag is not set). timeout OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional timeout count. The timeout argument is the address of a signed longword containing the timeout count. If the timeout argument is specified, all characters entered before the timeout are returned in the buffer. If the timeout argument is omitted, characters are returned in the buffer until a terminator is encountered. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off word-terminator-code OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Key terminator code. The word-terminator-code argument is an unsigned word into which is written a code indicating what character or key terminated the read. Key terminator codes are of the form SMG$K_TRM_keyname. 3 SMG$READ_FROM_DISPLAY The Read Text from Display routine reads a line of text from a virtual display. Format SMG$READ_FROM_DISPLAY display-id ,resultant-string [,terminator-string] [,start-row] [,rendition-string] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display from which text is read. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which SMG$READ_FROM_DISPLAY writes the information read from the virtual display. The resultant-string argument is the address of a descriptor pointing to the string into which the string is written. terminator-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing a terminator or terminators that end the backward search, thus determining the starting position of the returned string. The terminator-string argument is the address of a descriptor pointing to the string of terminators. If terminator-string is omitted, no back searching is performed; the returned string starts with the character at the current cursor position. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference The start-row argument is the address of a signed longword that contains the row of the virtual display to read from. This is an optional argument. rendition-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Optional bit mask string that controls the video attributes. The rendition-string argument is the address of a descriptor pointing to the bit mask string. Each attribute set causes the corresponding attribute to be set for the corresponding byte in the text string in the display. The following attributes can be specified for each byte using the rendition-string argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_ Specifies invisible characters; that is, the INVISIBLE characters exist in the virtual display but do not appear on the pasteboard. 3 SMG$READ_KEYSTROKE The Read a Single Character routine reads a keystroke and returns that keystroke's terminator code. Format SMG$READ_KEYSTROKE keyboard-id ,word-terminator-code [,prompt-string] [,timeout] [,display-id] [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Keyboard identifier. The keyboard-id argument is an unsigned longword containing the identifier of the virtual keyboard from which to read. You can create a virtual keyboard by calling the SMG$CREATE_ VIRTUAL_KEYBOARD routine. word-terminator-code OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Key terminator code. The word-terminator-code argument is an unsigned word into which is written a code indicating what character or key terminated the read. Key terminator codes are of the form SMG$K_TRM_keyname. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Prompt string. The prompt-string argument is an optional string used as the prompt for the read operation. timeout OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Timeout count. The timeout argument is optional. If specified, any character typed before the timeout is returned in the buffer. display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier. The optional display-id argument is the address of an unsigned longword that contains the identifier of the virtual display in which the read is to be performed. If the optional prompt-string argument is specified while there are multiple virtual displays pasted, the display-id argument is required to determine in which virtual display the prompt string will be written. If the prompt-string argument is not specified, do not specify the display-id argument. In the case of multiple virtual displays, each virtual display has an associated virtual cursor position. At the same time, there is a single physical cursor position corresponding to the current location of the physical cursor. If the display-id argument is specified, the read begins at the current virtual cursor position in the specified virtual display. If display- id is omitted, the read begins in the current physical cursor position. Note that the length of the prompt-string plus the key entered is limited to the number of visible columns in the display. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$READ_LOCATOR The Read Locator Information routine reads information from a DECwindows workstation terminal's locator device (such as a mouse or tablet). Format SMG$READ_LOCATOR keyboard-id ,row-number ,column-number ,word-terminator-code [,timeout] [,parse-routine] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the desired virtual keyboard. You can create a virtual keyboard by calling the SMG$CREATE_ VIRTUAL_KEYBOARD routine. row-number OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Row number to which the locator is pointing. The row-number argument is the address of an unsigned word that contains the row number of the virtual display at which the locaor is pointing. column-number OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Column number to which the locator is pointing. The column-number argument is the address of an unsigned word that contains the column number of the virtual display at which the read is to be performed. word-terminator-code OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Locator terminator code. The word-terminator-code argument is the address of an unsigned word into which is written a code indicating what locator button terminated the read. Locator terminator codes are of the form SMG$K_TRM_keyname. timeout OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Timeout count. The optional timeout argument is the address of a signed longword that contains a number of seconds. If specified, any character typed before the timeout is returned in the buffer. parse-routine OpenVMS usage:longword_unsigned type: longword (signed) access: read only mechanism: by reference Address of a user-supplied parse routine that is called to parse the locator input. The optional parse-routine argument is the address of an unsigned longword that contains the parse routine. If this argument is not specified, ANSI locator input is assumed. 3 SMG$READ_STRING The Read String routine reads a string from a virtual keyboard. Format SMG$READ_STRING keyboard-id ,resultant-string [,prompt-string] [,maximum-length] [,modifiers] [,timeout] [,terminator-set] [,resultant-length] [,word-terminator-code] [,display-id] [,initial-string] [,rendition-set] [,rendition-complement] [,terminator-string] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual keyboard from which input is to be read. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier. The keyboard identifier is returned by SMG$CREATE_VIRTUAL_ KEYBOARD. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which the input line is written. The resultant-string argument is the address of a descriptor pointing to the string into which the text is written. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String used to prompt for the read operation. The prompt-string argument is the address of a descriptor pointing to the prompt string. maximum-length OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the maximum number of characters to be read. The maximum-length argument is the address of a signed longword that contains the maximum number of characters to be read. The maximum valid value for this argument is 512. If omitted, 512 is the default. modifiers OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies optional behavior. The modifiers argument is the address of an unsigned longword that contains the flag. Valid values for modifiers are as follows: TRM$M_TM_CVTLOW Converts lowercase characters to uppercase characters. TRM$M_TM_NOECHO Characters entered are not echoed on the screen. TRM$M_TM_NOEDIT Advanced editing is disabled for this read operation. TRM$M_TM_NORECALL Line recall is disabled. TRM$M_TM_PURGE Type-ahead buffer is purged before read is begun. TRM$M_TM_ Termination character, if any, is not TRMNOECHO displayed. The TRM$ symbols are defined by the $TRMDEF macro/module in system symbol libraries supplied by Compaq. See the terminal driver section of the OpenVMS I/O User's Reference Manual for more information on modifiers for read operations. timeout OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of seconds allowed between the time the prompt is issued and the completion of the input operation. The timeout argument is the address of a signed longword that contains the timeout value. If timeout is specified, all characters typed before the expiration time or until a terminate key is entered are returned in resultant-string. If omitted, the input operation remains active until a terminator is typed. terminator-set OpenVMS usage:unspecified type: unspecified access: read only mechanism: by descriptor, fixed length Either a mask that specifies which characters are to be treated as terminators (short form) or a descriptor pointing to such a mask (long form). The terminator-set argument is the address of a descriptor pointing to the mask. If you want to use terminators with ASCII values in the range 0 to 31, use the short form, which consists of two longwords. The first longword is zero, and the second longword is a terminator character bit mask. You create this mask by setting the bit that corresponds to the ASCII value of the desired terminator. For example, to specify that Ctrl/A (ASCII value 1) is a terminator, you set bit 1 in the terminator-set mask. To use terminators with ASCII values outside the range 0 to 31, use the long form. First create a descriptor of this form: 31 16 15 0 ---------------------------------------------------------------- | | | | (not used) | mask size in bytes | | | | ---------------------------------------------------------------- | | | address of mask | | | ---------------------------------------------------------------- The mask itself has the same format as that of the short form; however, the long form allows the use of a more comprehensive set of terminator characters. For example, a mask size of 16 bytes allows any 7-bit ASCII character to be set as a terminator, while a mask size of 32 bytes allows any 8-bit character to be set as a terminator. Any mask size between 1 and 32 bytes is acceptable. If the terminator mask is all zeros, there are no specified terminators. In that case, the read terminates when the number of characters specified in maximum-length has been transferred or when timeout is reached. If the terminator-set argument is omitted, the set of terminators is the OpenVMS default terminator set. For more information, see the OpenVMS I/O User's Reference Manual. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Receives the number of characters read or the maximum size of resultant-string, whichever is less. The resultant-length argument is the address of an unsigned word into which is written the number of characters read or the maximum size. word-terminator-code OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Key terminator code. The word-terminator-code argument is an unsigned word into which is written a code indicating what character or key terminated the read. Key terminator codes are of the form SMG$K_TRM_keyname. display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier. The display-id argument is the address of an unsigned longword that contains the display identifier. This argument is optional only if you are not using the Screen Management Facility's output routines. If you are using the Screen Management Facility input and output routines, this argument specifies the virtual display in which the input is to occur. The virtual display specified must be pasted to the same pasteboard as specified by keyboard-id and must not be occluded. You cannot accept input from an occluded area of the virtual display. In the case of multiple virtual displays, each virtual display has an associated virtual cursor position. At the same time, there is a single physical cursor position corresponding to the current location of the physical cursor. If the display-id argument is specified, the read begins at the current virtual cursor position in the specified virtual display. If display- id is omitted, the read begins in the current physical cursor position. Note that the length of the prompt-string plus the key entered is limited to the number of visible columns in the display. NOTE This virtual display must be pasted in column 1 and may not have any other virtual displays to its right. This restriction applies because otherwise the occurrence of a Ctrl/R or Ctrl/U would cause the entire line to be blanked, including any output to the right. To circumvent this restriction, you may use SMG$REPAINT_LINE to repaint the line when a Ctrl/R or Ctrl/U is detected. initial-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Initial character string. The initial-string argument is the address of a descriptor pointing to the optional string that contains the initial characters of the field. The string is written to the display in the input area, as if it had been entered from the keyboard. It may be edited in the usual way (provided that TRM$M_TM_NOEDIT is not set). It must be shorter than maximum-length, otherwise SMG$READ_STRING returns immediately without accepting any keyboard input. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity (bolded). SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite default rendition of the virtual display. SMG$M_UNDERLINE Displays underlined characters. SMG$M_INVISIBLE Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with rendition-complement. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display in which the read is done. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition- set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of current setting 1 1 Attribute off terminator-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Characters that terminate I/O. The optional terminator-string argument is the address of a descriptor pointing to the character string containing the terminating characters. The terminator- string argument returns the actual terminating characters, not the key that was pressed to terminate the I/O. 3 SMG$READ_VERIFY The Read and Verify a String routine reads a sequence of characters and verifies the sequence. Format SMG$READ_VERIFY keyboard-id ,resultant-string ,initial-string ,picture-string ,fill-character ,clear-character [,prompt-string] [,modifiers] [,timeout] [,placeholder-arg] [,initial-offset] [,word-terminator-code] [,display-id] [,alternate-echo-string] [,alternate-display-id] [,rendition-set] [,rendition-complement] [,input-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the virtual keyboard from which to read. The virtual keyboard is created by calling the SMG$CREATE_ VIRTUAL_KEYBOARD routine. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Output string into which SMG$READ_VERIFY writes the characters that are read. The resultant-string argument is the address of a descriptor pointing to this output string. initial-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Input string that contains the initial characters of the field. The initial-string argument is the address of a descriptor pointing to the input string. picture-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String that contains a picture of what the field is to look like. The picture-string argument is the address of a descriptor pointing to the picture string. For more information on the legal values for the picture string, see the terminal driver section of the OpenVMS I/O User's Reference Manual. fill-character OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Fill character. The fill-character argument is the address of a descriptor pointing to the string that contains the character to be used as a fill character in the initial-string argument. clear-character OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Clear character. The clear-character argument is the address of a descriptor pointing to the string that contains the character to be displayed for each occurrence of fill-character in initial- string. prompt-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Prompt string. The prompt-string argument is the address of a descriptor pointing to the string that SMG$READ_VERIFY uses as the prompt for the read operation. This is an optional argument. modifiers OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Modifiers. The modifiers argument is a longword bit mask that specifies optional behavior. The bits defined are the same as for the $QIO item-list entry TRM$_MODIFIERS. This is an optional argument. Valid values for modifiers are as follows: TRM$M_TM_AUTO_TAB Field is full when last character is entered. TRM$M_TM_CVTLOW Converts lowercase characters to uppercase characters. TRM$M_TM_NOECHO Characters entered are not echoed on the screen. TRM$M_TM_NOEDIT Advanced editing is disabled for this read operation. TRM$M_TM_NORECALL Line recall is disabled. TRM$M_TM_PURGE Type-ahead buffer is purged before read is begun. TRM$M_TM_R_JUST Input is right justified. TRM$M_TM_ Termination character, if any, is not TRMNOECHO displayed. The TRM$ symbols are defined by the $TRMDEF macro/module in system symbol libraries supplied by Compaq. See the terminal driver section of the OpenVMS I/O User's Reference Manual for more information on modifiers for read operations. timeout OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Timeout count. The timeout argument is the address of a signed longword that contains the timeout value. The timeout argument is optional. If timeout is specified, all characters typed in before the timeout or before a terminator is entered are returned in the buffer. If timeout is omitted, characters are returned in the buffer until a terminator is seen. placeholder-arg OpenVMS usage:unspecified type: unspecified access: read only mechanism: unspecified Placeholder argument. The OpenVMS terminal driver ignores this argument when performing a read-verify. initial-offset OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Input string offset. The initial-offset argument is the address of a signed longword that contains the number of characters (from the initial-string argument) to output after the prompt before waiting for input. word-terminator-code OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Key terminator code. The word-terminator-code argument is an unsigned word into which SMG$READ_VERIFY writes a code indicating what character or key terminated the read. Key terminator codes are of the form SMG$K_TRM_keyname. display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier. The optional display-id argument is the address of an unsigned longword that contains the identifier of the virtual display in which the read is to be performed. If display-id is specified, SMG$READ_VERIFY begins the read at the current virtual cursor position in that virtual display. If omitted, the read begins in the current physical cursor position. You cannot accept input from an occluded area of the virtual display. In the case of multiple virtual displays, each virtual display has an associated virtual cursor position. At the same time, there is a single physical cursor position corresponding to the current location of the physical cursor. If the display-id argument is specified, the read begins at the current virtual cursor position in the specified virtual display. If omitted, the read begins in the current physical cursor position. Note that the length of the prompt-string, the initial-offset, and the string entered is limited to the number of visible columns in the display. alternate-echo-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Alternate echo string. The alternate-echo-string argument is a string that is printed after the first character is typed during the read operation. This is an optional argument. alternate-display-id OpenVMS usage:identifier type: longword (signed) access: read only mechanism: by reference Alternate display identifier. The alternate-display-id is a signed longword containing the identifier of the virtual display in which the alternate-echo-string argument is to be printed. This is an optional argument. If specified, the output begins at the current virtual cursor position in that virtual display. If omitted, the value of the display-id argument is used as the default. If display-id is not specified, the output begins in the current physical cursor position. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_UNDERLINE Displays underlined characters. SMG$M_INVISIBLE Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard. SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display in which the read is done. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition- set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the transformations shown in the following table. Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off input-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of characters entered by the user. The input-length argument is the address of an unsigned word containing this number. 3 SMG$REMOVE_LINE The Remove a Line from a Virtual Display routine removes a line from a specified virtual display that was drawn with the SMG$DRAW_LINE or SMG$DRAW_RECTANGLE routines. Format SMG$REMOVE_LINE display-id ,start-row ,start-column ,end-row ,end-column 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display from which the line is to be removed. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row at which to begin removing the line. The start- row argument is the address of a signed longword that contains the row number. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which to begin removing the line. The start-column argument is the address of a signed longword that contains the column number. end-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row at which the line to be removed ends. The end- row argument is the address of a signed longword that contains the row number. end-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column at which the line to be removed ends. The end-column argument is the address of a signed longword that contains the column number. 3 SMG$REPAINT_LINE The Repaint One or More Lines on the Current Pasteboard routine repaints a series of lines on the current pasteboard. Format SMG$REPAINT_LINE pasteboard-id ,start-row [,number-of-lines] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Pasteboard identifier. The pasteboard-id argument is the address of the pasteboard associated with the physical screen to be repainted. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Starting row number. The start-row argument is the address of the pasteboard row number to start repainting. number-of-lines OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of contiguous lines to repaint. The number-of-lines argument is the address of a signed longword containing the number of lines. This argument is optional. If not specified, the default is 1. 3 SMG$REPAINT_SCREEN The Repaint Current Pasteboard routine repaints the specified pasteboard after non-SMG$ I/O has occurred. Format SMG$REPAINT_SCREEN pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be repainted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. 3 SMG$REPASTE_VIRTUAL_DISPLAY The Repaste Virtual Display routine moves a virtual display to a new position on the pasteboard. The pasting order is not preserved. Format SMG$REPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id ,pasteboard-row ,pasteboard-column [,top-display-id] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be repasted. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard on which the display is repasted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the pasteboard row that is to contain row 1 of the specified virtual display. The pasteboard-row argument is the address of a signed longword that contains the pasteboard row. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the pasteboard column that is to contain column 1 of the specified virtual display. The pasteboard-column argument is the address of a signed longword that contains the pasteboard column. top-display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Optional identifier of the virtual display under which display- id will be pasted. The top-display-id argument is the address of an unsigned longword containing the identifier of this virtual display. Note that the virtual display specified by top-display- id must already be pasted. 3 SMG$REPLACE_INPUT_LINE The Replace Input Line routine replaces the specified lines in the recall buffer with the specified string. Format SMG$REPLACE_INPUT_LINE keyboard-id [,replace-string] [,line-count] [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the virtual keyboard from which to read. You create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_ KEYBOARD routine. replace-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String that contains the line to be entered into the recall buffer. The replace-string argument is the address of a descriptor pointing to this string. The default is a null string, which removes the last line entered. line-count OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Number of lines to be replaced. The line-count argument is the address of an unsigned byte containing the number of lines to be replaced with replace-string. The default value for the line- count argument is 1 (the last line entered). flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies optional behavior. The flags argument is the address of an unsigned longword that contains the flag. There is one valid value: SMG$M_KEEP_CONTENTS The string specified by replace-string replaces the existing string specified by line-count. By using this flag in a loop, the line recall buffer can be preloaded with information by the application. 3 SMG$RESTORE_PHYSICAL_SCREEN The Restore Physical Pasteboard routine rewrites the pasteboard image as it was at the time the SMG$SAVE_PHYSICAL_SCREEN routine was called. Format SMG$RESTORE_PHYSICAL_SCREEN pasteboard-id ,display-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard to be restored. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by the SMG$CREATE_ PASTEBOARD routine. display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display created by the SMG$SAVE_PHYSICAL_ SCREEN routine. The display-id argument is the address of an unsigned longword that contains this display identifier. 3 SMG$RETURN_CURSOR_POS The Return Cursor Position routine returns the current virtual cursor position in a specified virtual display. Format SMG$RETURN_CURSOR_POS display-id ,start-row ,start-column 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display whose current virtual cursor position you are requesting. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the virtual cursor's current row position within the specified virtual display. The start-row argument is the address of a signed longword into which is written the current row position. start-column OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Receives the virtual cursor's current column position within the specified virtual display. The start-column argument is the address of a signed longword into which is written the current column position. 3 SMG$RETURN_INPUT_LINE The Return Input Line routine returns to the caller the requested line from the recall buffer. This line is retrieved either by matching it with a specified string or by specifying the appropriate line number. Format SMG$RETURN_INPUT_LINE keyboard-id ,resultant-string [,match-string] [,byte-integer-line-number] [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Keyboard identifier. The keyboard-id argument is the address of an unsigned longword containing the identifier of the virtual keyboard from which to read. The virtual keyboard is created by calling the SMG$CREATE_ VIRTUAL_KEYBOARD routine. resultant-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor String into which is written the complete recalled line. The resultant-string argument is the address of a descriptor pointing to this string. match-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Match string to be used when searching for the line to be recalled. The optional match-string argument is the address of a descriptor pointing to this match string. The search begins with the last line typed. byte-integer-line-number OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Line number to be used when searching for the line to be recalled. The optional byte-integer-line-number argument is the address of an unsigned byte containing the number of the line to be recalled. The last line typed is line number 1. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the resultant-string string. The optional resultant- length argument is the address of an unsigned word containing either the number of characters read or the maximum length of resultant-string, whichever is less. 3 SMG$RING_BELL The Ring the Terminal Bell or Buzzer routine sounds the terminal bell or buzzer. Format SMG$RING_BELL display-id [,number-of-times] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display for which the bell or buzzer sounds. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. number-of-times OpenVMS usage:longword_signed type: longword integer (signed) access: read only mechanism: by reference Specifies the number of times the bell or buzzer is sounded. The number-of-times argument is the address of a signed longword integer that contains the number of times the bell or buzzer is sounded. If number-of-times is omitted, 1 is used. 3 SMG$SAVE_PHYSICAL_SCREEN The Save Physical Screen routine saves the contents of the pasteboard so that a later call to SMG$RESTORE_PHYSICAL_SCREEN can restore it. Format SMG$SAVE_PHYSICAL_SCREEN pasteboard-id ,display-id [,desired-start-row] [,desired-end-row] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard whose contents are to be saved. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. display-id OpenVMS usage:identifier type: longword (unsigned) access: write only mechanism: by reference Receives the display identifier of the display created to contain the contents of the specified pasteboard. The display-id argument is the address of an unsigned longword into which the display identifier is written. The display identifier must be passed to the SMG$RESTORE_ PHYSICAL_SCREEN routine to restore the saved information. desired-start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the first row to be saved. The desired-start-row argument is the address of a signed longword that contains the row number. If desired-start-row is omitted, row 1 of the pasteboard is used. desired-end-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the last row to be saved. The desired-end-row argument is the address of a signed longword that contains the row number. If desired-end-row is omitted, the last row of the pasteboard is used. 3 SMG$SAVE_VIRTUAL_DISPLAY The Save the Virtual Display to a File routine saves the contents of a virtual display and stores it in a file. Format SMG$SAVE_VIRTUAL_DISPLAY display-id [,filespec] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be saved. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. filespec OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing the file specification of the file in which the specified virtual display is saved. The filespec argument is the address of a descriptor pointing to the character string containing the file specification. A new file is created each time this routine is called. If filespec is omitted, the default file specification is SMGDISPLY.DAT. 3 SMG$SCROLL_DISPLAY_AREA The Scroll Display Area routine scrolls a rectangular region of a virtual display. Format SMG$SCROLL_DISPLAY_AREA display-id [,start-row] [,start-column] [,height] [,width] [,direction] [,count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display in which scrolling takes place. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the first row of the scrolling region. The start-row argument is the address of a signed longword that contains the starting row. If start-row is omitted, row 1 of the specified virtual display is used. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the first column of the scrolling region. The start- column argument is the address of a signed longword that contains the starting column. If omitted, column 1 of the specified virtual display is used. height OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of rows in the scrolling region. The height argument is the address of a signed longword that contains the number of rows. If omitted, this value defaults to either the height of the virtual scrolling region (if one has been explicitly set with SMG$SET_DISPLAY_SCROLL_REGION) or the height of the specified virtual display. When scrolling a portion of a virtual display that contains double-height, double-width (highwide) characters, it is recommended that you scroll the display an even number of times. width OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of columns in the scrolling region. The width argument is the address of a signed longword that contains the number of columns. If omitted, this value defaults to the width of the specified virtual display. direction OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies the direction to scroll. The direction argument is the address of a longword bit mask that contains the direction code. Valid values are SMG$M_UP, SMG$M_DOWN, SMG$M_RIGHT, and SMG$M_ LEFT. SMG$M_UP is the default. count OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of lines or columns to scroll. The count argument is the address of a signed longword that contains the number of units (lines or columns) to scroll. If omitted, one unit is scrolled. 3 SMG$SCROLL_VIEWPORT The Scroll a Display Under a Viewport routine scrolls a virtual display under its associated viewport. Format SMG$SCROLL_VIEWPORT display-id [,direction] [,count] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Display identifier of the virtual display to be scrolled. The display-id argument is the address of an unsigned longword containing this identifier. direction OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional direction specifier. The direction argument is the address of a longword bit mask that contains the direction code specifying the scrolling direction. The optional count argument can be used to specify the number of lines to scroll in the specified direction. Valid values for direction are as follows: SMG$M_UP Scroll count lines upward. SMG$M_DOWN Scroll count lines downward. SMG$M_RIGHT Scroll count columns to the right. SMG$M_LEFT Scroll count columns to the left. SMG$M_UP is the default. count OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional number of rows or columns to be scrolled. The default is 1. 3 SMG$SELECT_FROM_MENU The Make a Selection from the Menu routine lets you move between the menu choices using the arrow keys and lets you make a selection by pressing the Return key. Format SMG$SELECT_FROM_MENU keyboard-id ,display-id ,selected-choice-number [,default-choice-number] [,flags] [,help-library] [,timeout] [,word-terminator-code] [,selected-choice-string] [,rendition-set] [,rendition-complement] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual keyboard from which the terminal user's responses are read. The keyboard-id argument is the address of an unsigned longword containing this identifier. display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the virtual display in which the choices are displayed. The display-id argument is the address of an unsigned longword containing this display identifier. This virtual display must be pasted to a pasteboard and cannot be batched or occluded. selected-choice-number OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Identification number of the menu item selected. The selected- choice-number argument is the address of an unsigned word that receives this number. The selected-choice-number corresponds to the index of the menu item in the static string array specified in SMG$CREATE_MENU. default-choice-number OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Optional identification number of the default menu item. The default-choice-number argument is the address of an unsigned word that contains the number of the default menu item. The default- choice-number corresponds to the index of the default menu item in the static string array specified in SMG$CREATE_MENU. If omitted, the default choice will be the last menu item already selected, or the first item in the menu if no selections have yet been made. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask indicating behavior when a selection is made. The flags argument is the address of an unsigned longword containing the flag. Valid values are as follows: SMG$M_RETURN_ Returns control to the user when any key other IMMED than an arrow key is entered. SMG$M_REMOVE_ Causes SMG$SELECT_FROM_MENU to allow each menu ITEM item to be selected only once. help-library OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Optional help library to use if the PF2/Help key is pressed. The help-library argument is the address of a descriptor pointing to this help library name. Note that this argument is ignored if flags specifies SMG$M_RETURN_IMMED. The default is SYS$HELP:HELPLIB.HLB. timeout OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Optional timeout value. The timeout argument is the address of a signed longword that specifies the number of seconds to wait for a selection to be made. word-terminator-code OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Optional unsigned word that receives the code indicating which key terminated the read. The word-terminator-code argument is the address of an unsigned word that receives this terminating key code. selected-choice-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Optional string that receives the text of the menu item selected. The selected-choice-string is the address of a descriptor pointing to this string. rendition-set OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument: SMG$M_BLINK Displays blinking characters. SMG$M_BOLD Displays characters in higher-than-normal intensity. SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display. SMG$M_ Displays underlined characters. UNDERLINE SMG$M_USER1 Displays user-defined attributes. through SMG$M_USER8 The display-id argument must be specified when you use the rendition-set argument. rendition-complement OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Attribute complement specifier. The optional rendition- complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument. The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition- complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations: Set Complement Action 0 0 Attribute set to default 1 0 Attribute on 0 1 Attribute set to complement of default setting 1 1 Attribute off 3 SMG$SET_BROADCAST_TRAPPING The Enable Broadcast Trapping routine enables the trapping of broadcast messages. Format SMG$SET_BROADCAST_TRAPPING pasteboard-id [,AST-routine] [,AST-argument] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard for which broadcast messages are to be trapped. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. AST-routine OpenVMS usage:ast_procedure type: procedure value access: read only mechanism: by value The address of an AST routine to be called when a message is received at the pasteboard. The AST-routine argument is the address of the routine's procedure value. When the AST-routine argument is either omitted or is given a value of 0, the BROADCAST mode is set to synchronize. In this mode, you must periodically call SMG$GET_BROADCAST_MESSAGE to see if any broadcast messages have arrived. The AST routine is called with five parameters: AST-argument, R0, R1, PC, and PSL (on VAX systems) or PS (on Alpha systems). AST-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value A value to be passed to the AST routine. The AST-argument is an unsigned longword that contains the value to be passed to the AST routine. 3 SMG$SET_CURSOR_ABS The Set Absolute Cursor Position routine moves the virtual cursor to the specified position in a virtual display. Format SMG$SET_CURSOR_ABS display-id [,start-row] [,start-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display in which to set the virtual cursor position. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row position to which the virtual cursor moves. The start-row argument is the address of a signed longword that contains the row number. If omitted, the cursor remains at the current row. start-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column position to which the virtual cursor moves. The start-column argument is the address of a signed longword that contains the column number. If omitted, the virtual cursor remains at the current column. 3 SMG$SET_CURSOR_MODE The Set the Cursor Mode routine turns the physical cursor on or off and selects jump or smooth scrolling. Format SMG$SET_CURSOR_MODE pasteboard-id ,flags 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Pasteboard identifier. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies scrolling and cursor attributes. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values: SMG$M_CURSOR_OFF Clears physical cursor. SMG$M_CURSOR_ON Displays physical cursor. SMG$M_SCROLL_JUMP Jump scrolls. SMG$M_SCROLL_ Smooth scrolls. SMOOTH 3 SMG$SET_CURSOR_REL The Move Cursor Relative to Current Position routine moves the virtual cursor the specified number of rows and columns from the current virtual cursor position in a virtual display. Format SMG$SET_CURSOR_REL display-id [,delta-row] [,delta-column] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display in which to move the virtual cursor. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. delta-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of rows to move the virtual cursor. The delta-row argument is the address of a signed longword that contains the number of rows to move. If omitted, the virtual cursor remains at the current row position. If delta-row is positive, the virtual cursor moves downward the specified number of rows. If delta-row is negative, the virtual cursor moves upward the specified number of rows. delta-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the number of columns to move the cursor. The delta- column argument is the address of a signed longword that contains the number of columns to move. If omitted, the virtual cursor remains at the current column position. If delta-column is positive, the virtual cursor moves the specified number of columns to the right. If delta-column is negative, the virtual cursor moves the specified number of columns to the left. 3 SMG$SET_DEFAULT_STATE The Set Default State routine sets and/or returns the current default state for a key table. Format SMG$SET_DEFAULT_STATE key-table-id [,new-state] [,old-state] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments key-table-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the key table in which you are setting or inquiring about a default state. The key-table-id argument is the address of an unsigned longword that contains the key table identifier. The key table identifier is returned by the SMG$CREATE_KEY_TABLE routine. new-state OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Specifies the new default state for the entire key table. The new-state argument is the address of a descriptor pointing to the new state string. The specified state name is converted to uppercase and stripped of trailing blanks before use. old-state OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Receives the existing default state name of the specified key definition table. The old-state argument is the address of a descriptor pointing to the string into which the old state string is written. 3 SMG$SET_DISPLAY_SCROLL_REGION The Create Display Scrolling Region routine creates a virtual scrolling region in a virtual display. Format SMG$SET_DISPLAY_SCROLL_REGION display-id [,start-row] [,end-row] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display in which scrolling takes place. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. start-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the first line of the virtual scrolling region. The start-row argument is the address of a signed longword that contains the starting line number. If omitted, the first line of the display is used. end-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the last line of the virtual scrolling region. The end- row argument is the address of a signed longword that contains the ending line number. If omitted, the last line of the virtual display is used. 3 SMG$SET_KEYPAD_MODE The Set Keypad Mode routine sets the terminal's numeric keypad to either numeric or applications mode. Format SMG$SET_KEYPAD_MODE keyboard-id ,flags 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments keyboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual keyboard whose mode is to be changed. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier. The keyboard identifier is returned by SMG$CREATE_VIRTUAL_ KEYBOARD. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies whether the keypad is to be in applications or numeric mode. The flags argument is the address of an unsigned longword that contains the flag. Valid values for flags are as follows: 0 Keypad is set to numeric mode. SMG$M_KEYPAD_ Keypad is set to applications mode. APPLICATION 3 SMG$SET_OUT_OF_BAND_ASTS The Set Out-of-Band ASTs routine either enables or disables the trapping of out-of-band control characters. Format SMG$SET_OUT_OF_BAND_ASTS pasteboard-id,control-character-mask ,AST-routine [,AST-argument] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard for which out-of-band characters are enabled or disabled. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. control-character-mask OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Specifies which control characters are to be the new out-of-band control characters. The control-character-mask argument is the address of an unsigned longword that contains the mask. Create this mask by setting the bit that corresponds to the ASCII value of the desired character. For example, to specify that Ctrl/C (ASCII value 3) is an out-of-band control character, set bit 3 (value 8) in the control-character-mask. If no bits are set in this mask, then no out-of-band ASTs occur. For more information, see the OpenVMS I/O User's Reference Manual. AST-routine OpenVMS usage:ast_procedure type: procedure value access: read only mechanism: by value The address of an AST routine to be called when an out-of-band control character is typed at the terminal. The AST-routine argument is the routine's procedure value. AST-argument OpenVMS usage:user_arg type: longword (unsigned) access: read only mechanism: by value The argument you supply to the AST. AST-argument is an unsigned longword that contains the value to be passed to the AST routine. However, the AST routine may also need to determine the out- of-band character and the pasteboard-id at which it was typed. Therefore, the Screen Management Facility creates a three- longword structure to hold this information and passes the address of this structure as the first argument to the AST routine. The remaining four arguments are R0, R1, PC, and PSL (on VAX systems) or PS (on Alpha systems). The Screen Management Facility stores the argument you supply in this structure. +---------------------------+ +-------------------------+ | address of data structure |--------->| SMG$L_PBD_ID | +---------------------------+ +-------------------------+ | R0 | | SMG$L_USER_ARG | +---------------------------+ +-------------------------+ | R1 | | SMG$L_CHAR | +---------------------------+ +-------------------------+ | PC | +---------------------------+ | PSL | +---------------------------+ The first longword contains the pasteboard-id and has the symbolic name SMG$L_PBD_ID. The second longword contains the AST-argument and has the symbolic name SMG$L_USER_ARG. The third longword contains the ASCII value of the out-of-band character typed and can be accessed by way of two symbolic names: SMG$B_ CHAR (the low-order byte containing the ASCII value), and SMG$L_ CHAR (the longword containing the ASCII value in the low-order byte and spaces in the high-order bytes). 3 SMG$SET_PHYSICAL_CURSOR The Set Cursor on Physical Screen routine moves the physical cursor to the specified position on the pasteboard. Format SMG$SET_PHYSICAL_CURSOR pasteboard-id ,pasteboard-row ,pasteboard-column 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard whose physical cursor is to move. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. pasteboard-row OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the row to which the physical cursor moves. The pasteboard-row argument is the address of a signed longword that contains the row number. pasteboard-column OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Specifies the column to which the physical cursor moves. The pasteboard-column argument is the address of a signed longword that contains the column number. 3 SMG$SET_TERM_CHARACTERISTICS The Change Terminal Characteristics routine changes or retrieves the terminal characteristics for a given pasteboard. Format SMG$SET_TERM_CHARACTERISTICS pasteboard-id [,on-characteristics1] [,on-characteristics2] [,off-characteristics1] [,off-characteristics2] [,old-characteristics1] [,old-characteristics2] [,on-characteristics3] [,off-characteristics3] [,old-characteristics3] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard whose characteristics are to be changed or retrieved. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD. on-characteristics1 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that specifies the terminal characteristics to be set from $TTDEF. The on-characteristics1 argument is the address of an unsigned longword that contains the bit mask. on-characteristics2 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that specifies the terminal characteristics to be set from $TT2DEF. The on-characteristics2 argument is the address of an unsigned longword that contains the bit mask. off-characteristics1 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that specifies the terminal characteristics to be reset from $TTDEF. The off-characteristics1 argument is the address of an unsigned longword that contains the bit mask. off-characteristics2 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that specifies the terminal characteristics to be reset from $TT2DEF. The off-characteristics2 argument is the address of an unsigned longword that contains the bit mask. old-characteristics1 OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Retrieves the current terminal characteristics in the first group. The old-characteristics1 argument is the address of an unsigned longword that contains the bit mask. old-characteristics2 OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Retrieves the current terminal characteristics in the second group. The old-characteristics2 argument is the address of an unsigned longword that contains the bit mask. on-characteristics3 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that specifies the terminal characteristics to be set from $TT3DEF. The on-characteristics3 argument is the address of an unsigned longword that contains the bit mask. off-characteristics3 OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Bit mask that specifies the terminal characteristics to be reset from $TT3DEF. The off-characteristics3 argument is the address of an unsigned longword that contains the bit mask. old-characteristics3 OpenVMS usage:mask_longword type: longword (unsigned) access: write only mechanism: by reference Retrieves the current terminal characteristics in the third group. The old-characteristics3 argument is the address of an unsigned longword that contains the bit mask. 3 SMG$SNAPSHOT The Write Snapshot routine writes the current pasteboard buffer to the file or hardcopy terminal specified by the pasteboard identifier. Format SMG$SNAPSHOT pasteboard-id [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the file or hardcopy terminal to receive the contents of the pasteboard buffer. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. The output device associated with pasteboard-id is specified by the output-device argument of SMG$CREATE_PASTEBOARD. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies whether a form feed is passed. The flags argument is the address of an unsigned longword containing the flag. Valid values for flags are as follows: 0 No form feed is passed. SMG$M_FORM_FEED The first line passed is a form feed. 3 SMG$SNAPSHOT_TO_PRINTER The Write Snapshot to Printer routine writes the current pasteboard buffer to the printer attached to the terminal. Format SMG$SNAPSHOT_TO_PRINTER pasteboard-id ,device-type [,flags] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Identifier of the pasteboard whose snapshot will be sent to a printer. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. device-type OpenVMS usage:device_name type: character string access: read only mechanism: by descriptor Specifies the type of printer to which the output associated with this pasteboard will be written. The device-type argument is the address of a descriptor that points to the name of the output device. Valid values for this argument (for example, LA50) are defined in SYS$SYSTEM:TERMTABLE.TXT. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Optional bit mask that specifies whether a form feed is passed. The flags argument is the address of an unsigned longword containing the flag. The valid value for the flags argument is as follows: SMG$M_FORM_FEED Output a form feed as the first record. 3 SMG$UNPASTE_VIRTUAL_DISPLAY The Remove Virtual Display routine removes a virtual display from a pasteboard. Format SMG$UNPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments display-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the virtual display to be removed from a pasteboard. The display-id argument is the address of an unsigned longword that contains the display identifier. The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY. pasteboard-id OpenVMS usage:identifier type: longword (unsigned) access: read only mechanism: by reference Specifies the pasteboard from which the virtual display is removed. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier. 2 STR$ 3 STR$ADD The Add Two Decimal Strings routine adds two decimal strings of digits. Format STR$ADD asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign ,cexp ,cdigits 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments asign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the first operand. The asign argument is the address of an unsigned longword containing this sign. A value of 0 is considered positive; a value of 1 is considered negative. aexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which adigits is multiplied to get the absolute value of the first operand. The aexp argument is the address of a signed longword containing this exponent. adigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Text string of unsigned digits representing the absolute value of the first operand before aexp is applied. The adigits argument is the address of a descriptor pointing to this string. This string must be an unsigned decimal number. bsign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the second operand. The bsign argument is the address of an unsigned longword containing the second operand's sign. A value of 0 is considered positive; a value of 1 is considered negative. bexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which bdigits is multiplied to get the absolute value of the second operand. The bexp argument is the address of a signed longword containing the second operand's exponent. bdigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Text string of unsigned digits representing the absolute value of the second operand before bexp is applied. The bdigits argument is the address of a descriptor pointing to this string. This string must be an unsigned decimal number. csign OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Sign of the result. The csign argument is the address of an unsigned longword containing the result's sign. A value of 0 is considered positive; a value of 1 is considered negative. cexp OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Power of 10 by which cdigits is multiplied to get the absolute value of the result. The cexp argument is the address of a signed longword containing this exponent. cdigits OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Text string of unsigned digits representing the absolute value of the result before cexp is applied. The cdigits argument is the address of a descriptor pointing to this string. This string is an unsigned decimal number. 3 STR$ANALYZE_SDESC The Analyze String Descriptor routine extracts the length and starting address of the data for a variety of string descriptor classes. Format STR$ANALYZE_SDESC input-descriptor ,integer-length ,data-address 4 Corresponding_JSB_Entry_Point STR$ANALYZE_SDESC_R1 4 Returns OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by value Length of the data. The return value is the same value returned to the integer-length argument. 4 Arguments input-descriptor OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Input descriptor from which STR$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. integer-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference for CALL entry point, by value for JSB entry point Length of the data; this length is extracted from the descriptor by STR$ANALYZE_SDESC. The integer-length argument is the address of an unsigned word integer into which STR$ANALYZE_SDESC writes the data length. data-address OpenVMS usage:address type: longword (unsigned) access: write only mechanism: by reference for CALL entry point, by value for JSB entry point Address of the data; this address is extracted from the descriptor by STR$ANALYZE_SDESC. The data-address argument is an unsigned longword into which STR$ANALYZE_SDESC writes the address of the data. 3 STR$ANALYZE_SDESC_64 (Alpha only.) The Analyze String Descriptor routine extracts the length and starting address of the data for a variety of string descriptor classes. Format STR$ANALYZE_SDESC_64 input-descriptor ,integer-length ,data-address [,descriptor-type] 4 Corresponding_JSB_Entry_Point STR$ANALYZE_SDESC_R1 Refer to the STR$ANALYZE_SDESC routine for information about the JSB entry point, STR$ANALYZE_SDESC_R1. This JSB entry point returns 64-bit results on Alpha systems. 4 Returns OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: write only mechanism: by value Length of the data. The return value is the same value returned to the integer-length argument. 4 Arguments input-descriptor OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Input descriptor from which STR$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). integer-length OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: write only mechanism: by reference for CALL entry point, by value for JSB entry point Length of the data; this length is extracted from the descriptor by STR$ANALYZE_SDESC_64. The integer-length argument is the address of an unsigned quadword integer into which STR$ANALYZE_ SDESC_64 writes the data length. data-address OpenVMS usage:address type: quadword (unsigned) access: write only mechanism: by reference for CALL entry point, by value for JSB entry point Address of the data; this address is extracted from the descriptor by STR$ANALYZE_SDESC_64. The data-address argument is an unsigned quadword into which STR$ANALYZE_SDESC_64 writes the address of the data. descriptor-type OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Flag value indicating the type of input descriptor. The descriptor-type argument contains the address of an unsigned word integer to which STR$ANALYZE_SDESC_64 writes a zero (0) for a 32-bit input descriptor or a one (1) for a 64-bit descriptor. This argument is optional. 3 STR$APPEND The Append String routine appends a source string to the end of a destination string. Format STR$APPEND destination-string ,source-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string to which STR$APPEND appends the source string. The destination-string argument is the address of a descriptor pointing to the destination string. This destination string must be dynamic or varying length. The maximum length of the destination string for a 32-bit descriptor is 2**16-1, or 65,535, bytes. On Alpha systems, the maximum length of the destination string for all 64-bit descriptor classes, except varying-length strings, is 2**64-1 bytes. The maximum length of a varying-length string is 2**16-1 for both 32-bit and 64-bit descriptors. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string that STR$APPEND appends to the end of the destination string. The source-string argument is the address of a descriptor pointing to this source string. 3 STR$CASE_BLIND_COMPARE The Compare Strings Without Regard to Case routine compares two input strings of any supported class and data type without regard to whether the alphabetic characters are uppercase or lowercase. Format STR$CASE_BLIND_COMPARE first-source-string ,second-source-string 4 Returns OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by value The values returned by STR$CASE_BLIND_COMPARE and the conditions to which they translate are as follows: Returned Value Condition first-source-string is less than second-source- string. 0 Both are the same (with blank fill for shorter string). 1 first-source-string is greater than second-source- string. 4 Arguments first-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First string. The first-source-string argument is the address of a descriptor pointing to the first string. second-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second string. The second-source-string argument is the address of a descriptor pointing to the second string. 3 STR$COMPARE The Compare Two Strings routine compares the contents of two strings. Format STR$COMPARE first-source-string ,second-source-string 4 Returns OpenVMS usage:longword_signed type: longword integer (signed) access: write only mechanism: by value The values returned by STR$COMPARE and the conditions to which they translate are as follows: Returned Value Condition first-source-string is less than second-source- string. 0 first-source-string is equal to second-source- string. 1 first-source-string is greater than second-source- string. 4 Arguments first-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First string. The first-source-string argument is the address of a descriptor pointing to the first string. second-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second string. The second-source-string argument is the address of a descriptor pointing to the second string. 3 STR$COMPARE_EQL The Compare Two Strings for Equality routine compares two strings to see if they have the same length and contents. Uppercase and lowercase characters are not considered equal. Format STR$COMPARE_EQL first-source-string ,second-source-string 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The values returned by STR$COMPARE and the conditions to which they translate are as follows: Returned Value Condition 0 The length and the contents of first-source-string are equal to the length and contents of second- source-string. 1 Either the length of first-source-string is not equal to the length of second-source-string, or the contents of first-source-string are not equal to the contents of second-source-string, or both. 4 Arguments first-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First source string. The first-source-string argument is the address of a descriptor pointing to the first source string. second-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second source string. The second-source-string argument is the address of a descriptor pointing to the second source string. 3 STR$COMPARE_MULTI The Compare Two Strings for Equality Using Multinational Character Set routine compares two character strings for equality using the DEC Multinational Character Set. Format STR$COMPARE_MULTI first-source-string ,second-source-string [,flags-value] [,foreign-language] 4 Returns OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by value The values returned by STR$COMPARE_MULTI and the conditions to which they translate are as follows: Returned Value Condition first-source-string is less than second-source- string. 0 Both strings are the same; the shorter string is blank filled. 1 first-source-string is greater than second-source- string. 4 Arguments first-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First string in the comparison. The first-source-string argument is the address of a descriptor pointing to the first string. second-source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second string in the comparison. The second-source-string argument is the address of a descriptor pointing to the second string. flags-value OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by value A single flag bit. The flags-value argument is a signed longword integer that contains this flag bit. The flags-value argument indicates whether the comparison is to be case sensitive or case blind. The default value of flags-value is 0, indicating a case sensitive comparison. The following table lists the meaning of the bit values: Value Meaning 0 Uppercase and lowercase characters are not equivalent. (The comparison is case sensitive.) 1 Uppercase and lowercase characters are equivalent. (The comparison is case blind.) foreign-language OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by value Indicator that determines the foreign language table to be used. The foreign-language argument is an unsigned longword that contains this foreign language table indicator. The default value of foreign-language is 1. The following table lists the value of the foreign-language argument associated with each language table: Value Language 1 Multinational table 2 Danish table 3 Finnish/Swedish table 4 German table 5 Norwegian table 6 Spanish table 3 STR$CONCAT The Concatenate Two or More Strings routine concatenates all specified source strings into a single destination string. Format STR$CONCAT destination-string ,source-string [,source-string...] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$CONCAT concatenates all specified source strings. The destination-string argument is the address of a descriptor pointing to this destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First source string; STR$CONCAT requires at least one source string. The source-string argument is the address of a descriptor pointing to the first source string. The maximum number of source strings that STR$CONCAT allows is 254. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Additional source strings; STR$CONCAT requires at least one source string. The source-string argument is the address of a descriptor pointing to the additional source string. The maximum number of source strings that STR$CONCAT allows is 254. 3 STR$COPY_DX The Copy a Source String Passed by Descriptor to a Destination String routine copies a source string to a destination string. Both strings are passed by descriptor. Format STR$COPY_DX destination-string ,source-string 4 Corresponding_JSB_Entry_Point STR$COPY_DX_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$COPY_DX writes the source string. Depending on the class of the destination string, the following actions occur: Descriptor Class Action S, Z, SD, A, Copy the source string. If needed, fill space or NCA truncate on the right. D If the area specified by the destination descriptor is large enough to contain the source string, copy the source string and set the new length in the destination descriptor. If the area specified is not large enough, return the previous space allocation (if any) and then dynamically allocate the amount of space needed. Copy the source string and set the new length and address in the destination descriptor. VS Copy the source string to the destination string up to the limit of the descriptor's MAXSTRLEN field with no padding. Adjust the string's current length (CURLEN) field to the actual number of bytes copied. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string that STR$COPY_DX copies into the destination string; the descriptor class of the source string can be unspecified, fixed length, dynamic length, scalar decimal, array, noncontiguous array, or varying length. The source-string argument is the address of a descriptor pointing to this source string. (See the description of LIB$ANALYZE_SDESC for possible restrictions.) 3 STR$COPY_R The Copy a Source String Passed by Reference to a Destination String routine copies a source string passed by reference to a destination string passed by descriptor. Format STR$COPY_R destination-string ,word-integer-source-length ,source-string-address 4 Corresponding_JSB_Entry_Point STR$COPY_R_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$COPY_R copies the source string. The destination-string argument is the address of a descriptor pointing to the destination string. The class field determines the appropriate action. See the description of LIB$ANALYZE_SDESC for restrictions associated with specific descriptor classes. word-integer-source-length OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Length of the source string. The word-integer-source-length argument is the address of an unsigned word containing the length of the source string. source-string-address OpenVMS usage:char_string type: character string access: read only mechanism: by reference Source string that STR$COPY_R copies into the destination string. The source-string-address argument is the address of the source string. 3 STR$COPY_R_64 (Alpha only.) The Copy a Source String Passed by Reference to a Destination String routine copies a source string passed by reference to a destination string passed by descriptor. Format STR$COPY_R_64 destination-string ,quad-integer-source-length ,source-string-address 4 Corresponding_JSB_Entry_Point STR$COPY_R_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$COPY_R_64 copies the source string. The destination-string argument is the address of a descriptor pointing to the destination string. The class field determines the appropriate action. See the description of LIB$ANALYZE_SDESC for restrictions associated with specific descriptor classes. quad-integer-source-length OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: read only mechanism: by reference Length of the source string. The quad-integer-source-length argument is the address of an unsigned quadword containing the length of the source string. source-string-address OpenVMS usage:char_string type: character string access: read only mechanism: by reference Source string that STR$COPY_R_64 copies into the destination string. The source-string-address argument is the address of the source string. 3 STR$DIVIDE The Divide Two Decimal Strings routine divides two decimal strings. Format STR$DIVIDE asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,total-digits ,round-truncate-indicator ,csign ,cexp ,cdigits 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments asign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the first operand. The asign argument is the address of an unsigned longword containing the sign of the first operand. A value of 0 is considered positive; a value of 1 is considered negative. aexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which adigits is multiplied to get the absolute value of the first operand. The aexp argument is the address of the first operand's exponent. adigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First operand's numeric text string. The adigits argument is the address of a descriptor pointing to the first operand's numeric string. The string must be an unsigned decimal number. bsign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the second operand. The bsign argument is the address of an unsigned longword containing the second operand's string. A value of 0 is considered positive; a value of 1 is considered negative. bexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which bdigits is multiplied to get the absolute value of the second operand. The bexp argument is the address of the second operand's exponent. bdigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second operand's numeric text string. The bdigits argument is the address of a descriptor pointing to the second operand's number string. The string must be an unsigned decimal number. total-digits OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of digits to the right of the decimal point. The total- digits argument is the address of a signed longword containing the number of total digits. STR$DIVIDE uses this number to carry out the division. round-truncate-indicator OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Indicator of whether STR$DIVIDE is to round or truncate the result; a value of 0 means truncate; a value of 1 means round. The round-truncate-indicator argument is the address of a longword bit mask containing this indicator. csign OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Sign of the result. The csign argument is the address of an unsigned longword containing the sign of the result. A value of 0 is considered positive; a value of 1 is considered negative. cexp OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Power of 10 by which cdigits is multiplied to get the absolute value of the result. The cexp argument is the address of a signed longword containing the exponent. cdigits OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Result's numeric text string. The cdigits argument is the address of a descriptor pointing to the numeric string of the result. This string is an unsigned decimal number. 3 STR$DUPL_CHAR The Duplicate Character n Times routine generates a string containing n duplicates of the input character. If the destination string is an "empty" dynamic-length string descriptor, STR$DUPL_CHAR allocates and initializes the string. Format STR$DUPL_CHAR destination-string [,repetition-count] [,ASCII-character] 4 Corresponding_JSB_Entry_Point STR$DUPL_CHAR_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$DUPL_CHAR writes repetition- count copies of the input character. The destination-string argument is the address of a descriptor pointing to the destination string. The maximum length of the destination string for a 32-bit descriptor is 2**16-1, or 65,535, bytes. On Alpha systems, the maximum length of the destination string for all 64-bit descriptor classes, except varying strings, is 2**64-1 bytes. The maximum length of a varying-length string is 2**16-1 for both 32-bit and 64-bit descriptors. repetition-count OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of times ASCII-character is duplicated; this is an optional argument (if omitted, the default is 1). The repetition- count argument is the address of a signed longword containing the number. ASCII-character OpenVMS usage:char_string type: character string access: read only mechanism: by reference ASCII character that STR$DUPL_CHAR writes repetition-count times into the destination string. The ASCII-character argument is the address of a character string containing this character. This is an optional argument; if omitted, the default is a space. 3 STR$ELEMENT The Extract Delimited Element Substring routine extracts an element from a string in which the elements are separated by a specified delimiter. Format STR$ELEMENT destination-string ,element-number ,delimiter-string ,source-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$ELEMENT copies the selected substring. The destination-string argument is the address of a descriptor pointing to the destination string. element-number OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Element number of the delimited element substring to be returned. The element-number argument is the address of a signed longword containing the desired element number. Zero is used to represent the first delimited element substring, one is used to represent the second, and so forth. delimiter-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Delimiter string used to separate element substrings. The delimiter-string argument is the address of a descriptor pointing to the delimiter string. The delimiter-string argument must be exactly one character long. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string from which STR$ELEMENT extracts the requested delimited substring. The source-string argument is the address of a descriptor pointing to the source string. 3 STR$FIND_FIRST_IN_SET The Find First Character in a Set of Characters routine searches a string, comparing each character to the characters in a specified set of characters. The string is searched character by character, from left to right. STR$FIND_FIRST_IN_SET returns the position of the first character in the string that matches any of the characters in the selected set of characters. Format STR$FIND_FIRST_IN_SET source-string ,set-of-characters 4 Returns OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by value Position in source-string where the first match is found; zero if no match is found. On Alpha systems, if the relative position of the substring can exceed 2**32-1, assign the return value to a quadword to ensure that you retrieve the correct relative position. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String that STR$FIND_FIRST_IN_SET compares to the set of characters, looking for the first match. The source-string argument is the address of a descriptor pointing to the character string. set-of-characters OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Set of characters that STR$FIND_FIRST_IN_SET is searching for in the string. The source-string argument is the address of a descriptor pointing to the set of characters. 3 STR$FIND_FIRST_NOT_IN_SET The Find First Character That Does Not Occur in Set routine searches a string, comparing each character to the characters in a specified set of characters. The string is searched character by character, from left to right. STR$FIND_FIRST_NOT_IN_SET returns the position of the first character in the string that does not match any of the characters in the selected set of characters. Format STR$FIND_FIRST_NOT_IN_SET source-string ,set-of-characters 4 Returns OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by value Position in source-string where a nonmatch was found. On Alpha systems, if the relative position of the substring can exceed 2**32-1, assign the return value to a quadword to ensure that you retrieve the correct relative position. Returned Value Condition 0 Either all characters in source-string match some characters in set-of-characters, or there were no characters in set-of-characters. 1 Either the first nonmatching character in source- string was found in position 1, or there were no characters in source-string. N The first nonmatching character was found in position N within source-string. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String that STR$FIND_FIRST_NOT_IN_SET searches. The source-string argument is the address of a descriptor pointing to the string. set-of-characters OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor The set of characters that STR$FIND_FIRST_NOT_IN_SET compares to the string, looking for a nonmatch. The set-of-characters argument is the address of a descriptor pointing to this set of characters. 3 STR$FIND_FIRST_SUBSTRING The Find First Substring in Input String routine finds the first substring (in a provided list of substrings) occurring in a given string. Format STR$FIND_FIRST_SUBSTRING source-string ,index ,substring-index ,substring [,substring...] 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value The values returned by STR$FIND_FIRST_SUBSTRING and the conditions to which they translate are as follows: Returned Value Condition 0 source-string did not contain any of the specified substrings. 1 STR$FIND_FIRST_SUBSTRING found at least one of the specified substrings in source-string. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String that STR$FIND_FIRST_SUBSTRING searches. The source-string argument is the address of a descriptor pointing to the string. index OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Earliest position within source-string at which STR$FIND_FIRST_ SUBSTRING found a matching substring; zero if no matching substring was found. The index argument is the address of a signed longword containing this position. substring-index OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Ordinal number of the substring that matched (1 for the first, 2 for the second, and so on), or zero if STR$FIND_FIRST_SUBSTRING found no substrings that matched. The substring-index argument is the address of a signed longword containing this ordinal number. substring OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Specified substring for which STR$FIND_FIRST_SUBSTRING searches in source-string. The substring argument is the address of a descriptor pointing to the first substring. You can specify multiple substrings to search for. substring OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Additional specified substring for which STR$FIND_FIRST_SUBSTRING searches in source-string. The substring argument is the address of a descriptor pointing to the substring. You can specify multiple substrings to search for. 3 STR$FREE1_DX The Free One Dynamic String routine deallocates one dynamic string. Format STR$FREE1_DX string-descriptor 4 Corresponding_JSB_Entry_Point STR$FREE1_DX_R4 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Argument string-descriptor OpenVMS usage:char_string type: character string access: modify mechanism: by descriptor Dynamic string descriptor of the dynamic string that STR$FREE1_ DX deallocates. The string-descriptor argument is the address of a descriptor pointing to the string to be deallocated. The descriptor's CLASS field is checked. 3 STR$GET1_DX The Allocate One Dynamic String routine allocates a specified number of bytes of virtual memory to a specified dynamic string descriptor. Format STR$GET1_DX word-integer-length ,character-string 4 Corresponding_JSB_Entry_Point STR$GET1_DX_R4 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments word-integer-length OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Number of bytes that STR$GET1_DX allocates. The word-integer- length argument is the address of an unsigned word containing this number. character-string OpenVMS usage:char_string type: character string access: modify mechanism: by descriptor Dynamic string descriptor to which STR$GET1_DX allocates the area. The character-string argument is the address of the descriptor. The descriptor's CLASS field is checked. 3 STR$GET1_DX_64 (Alpha only.) The Allocate One Dynamic String routine allocates a specified number of bytes of virtual memory to a specified dynamic string descriptor. Format STR$GET1_DX_64 quad-integer-length ,character-string 4 Corresponding_JSB_Entry_Point STR$GET1_DX_R4 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments quad-integer-length OpenVMS usage:quadword_unsigned type: quadword (unsigned) access: read only mechanism: by reference Number of bytes that STR$GET1_DX_64 allocates. The quad-integer- length argument is the address of an unsigned quadword containing this number. character-string OpenVMS usage:char_string type: character string access: modify mechanism: by descriptor Dynamic string descriptor to which STR$GET1_DX_64 allocates the area. The character-string argument is the address of the descriptor. The descriptor's CLASS field is checked. 3 STR$LEFT The Extract a Substring of a String routine copies a substring beginning at the first character of a source string into a destination string. Format STR$LEFT destination-string ,source-string ,end-position 4 Corresponding_JSB_Entry_Point STR$LEFT_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$LEFT copies the substring. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string from which STR$LEFT extracts the substring that it copies into the destination string. The source-string argument is the address of a descriptor pointing to the source string. end-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Relative position in the source string at which the substring ends. The end-position argument is the address of a signed longword containing the ending position. STR$LEFT copies all characters in the source string from position 1 (the leftmost position) to the position number specified in this end-position argument. 3 STR$LEN_EXTR The Extract a Substring of a String routine copies a substring of a source string into a destination string. Format STR$LEN_EXTR destination-string ,source-string ,start-position ,longword-integer-length 4 Corresponding_JSB_Entry_Point STR$LEN_EXTR_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$LEN_EXTR copies the substring. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string from which STR$LEN_EXTR extracts the substring that it copies into the destination string. The source-string argument is the address of a descriptor pointing to the source string. start-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Relative position in the source string at which STR$LEN_EXTR begins copying the substring. The start-position argument is the address of a signed longword containing the starting position. longword-integer-length OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Number of characters in the substring that STR$LEN_EXTR copies to the destination string. The longword-integer-length argument is the address of a signed longword containing the length of the substring. 3 STR$MATCH_WILD The Match Wildcard Specification routine compares a pattern string that includes wildcard characters with a candidate string. Format STR$MATCH_WILD candidate-string ,pattern-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value Returns a condition value of STR$_MATCH if the strings match and STR$_NOMATCH if they do not match. 4 Arguments candidate-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String that is compared to the pattern string. The candidate- string argument is the address of a descriptor pointing to the candidate string. pattern-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor String containing wildcard characters. The pattern-string argument is the address of a descriptor pointing to the pattern string. The wildcards in the pattern string are translated when STR$MATCH_WILD searches the candidate string to determine if it matches the pattern string. 3 STR$MUL The Multiply Two Decimal Strings routine multiplies two decimal strings. Format STR$MUL asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign ,cexp ,cdigits 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments asign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the first operand. The asign argument is the address of an unsigned longword containing the first operand's sign. A value of 0 is considered positive; a value of 1 is considered negative. aexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which adigits is multiplied to get the absolute value of the first operand. The aexp argument is the address of a signed longword containing this exponent. adigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First operand's numeric text string. The adigits argument is the address of a descriptor pointing to the numeric string of the first operand. The string must be an unsigned decimal number. bsign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the second operand. The bsign argument is the address of an unsigned longword containing the sign of the second operand. A value of 0 is considered positive; a value of 1 is considered negative. bexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which bdigits is multiplied to get the absolute value of the second operand. The bexp argument is the address of a signed longword containing this exponent. bdigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second operand's numeric text string. The bdigits argument is the address of a descriptor pointing to the second operand's numeric string. The string must be an unsigned decimal number. csign OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Sign of the result. The csign argument is the address of an unsigned longword containing the sign of the result. A value of 0 is considered positive; a value of 1 is considered negative. cexp OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Power of 10 by which cdigits is multiplied to get the absolute value of the result. The cexp argument is the address of a signed longword containing this exponent. cdigits OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Result's numeric text string. The cdigits argument is the address of a descriptor pointing to the numeric string of the result. The string is an unsigned decimal number. 3 STR$POSITION The Return Relative Position of Substring routine searches for the first occurrence of a single substring within a source string. If STR$POSITION finds the substring, it returns the relative position of that substring. If the substring is not found, STR$POSITION returns a zero. Format STR$POSITION source-string ,substring [,start-position] 4 Corresponding_JSB_Entry_Point STR$POSITION_R6 4 Returns OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by value Relative position of the first character of the substring. Zero is the value returned if STR$POSITION did not find the substring. On Alpha systems, if the relative position of the substring can exceed 2**32-1, assign the return value to a quadword to ensure that you retrieve the correct relative position. 4 Arguments source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string within which STR$POSITION searches for the substring. The source-string argument is the address of a descriptor pointing to the source string. substring OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Substring for which STR$POSITION searches. The substring argument is the address of a descriptor pointing to the substring. start-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Relative position in the source string at which STR$POSITION begins the search. The start-position argument is the address of a signed longword containing the starting position. Although this is an optional argument, it is required if you are using the JSB entry point. If start-position is not supplied, STR$POSITION starts the search at the first character position of source-string. 3 STR$POS_EXTR The Extract a Substring of a String routine copies a substring of a source string into a destination string. Format STR$POS_EXTR destination-string ,source-string ,start-position ,end-position 4 Corresponding_JSB_Entry_Point STR$POS_EXTR_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$POS_EXTR copies the substring. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string from which STR$POS_EXTR extracts the substring that it copies into the destination string. The source-string argument is the address of a descriptor pointing to the source string. start-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference for CALL entry point, by value for JSB entry point Relative position in the source string at which STR$POS_EXTR begins copying the substring. The start-position argument is the address of a signed longword containing the starting position. end-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference for CALL entry point, by value for JSB entry point Relative position in the source string at which STR$POS_EXTR stops copying the substring. The end-position argument is the address of a signed longword containing the ending position. 3 STR$PREFIX The Prefix a String routine inserts a source string at the beginning of a destination string. The destination string must be dynamic or varying length. Format STR$PREFIX destination-string ,source-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string (dynamic or varying length). STR$PREFIX copies the source string into the beginning of this destination string. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string that STR$PREFIX copies into the beginning of the destination string. The source-string argument is the address of a descriptor pointing to the source string. 3 STR$RECIP The Reciprocal of a Decimal String routine takes the reciprocal of the first decimal string to the precision limit specified by the second decimal string and returns the result as a decimal string. Format STR$RECIP asign ,aexp ,adigits ,bsign ,bexp ,bdigits ,csign ,cexp ,cdigits 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments asign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the first operand. The asign argument is the address of an unsigned longword containing the first operand's sign. A value of 0 is considered positive; a value of 1 is considered negative. aexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which adigits is multiplied to get the absolute value of the first operand. The aexp argument is the address of a signed longword containing this exponent. adigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor First operand's numeric text string. The adigits argument is the address of a descriptor pointing to the first operand's numeric string. The string must be an unsigned decimal number. bsign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the second operand. The bsign argument is the address of an unsigned longword containing the sign of the second operand. A value of 0 is considered positive; a value of 1 is considered negative. bexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which bdigits is multiplied to get the absolute value of the second operand. The bexp argument is the address of a signed longword containing this exponent. bdigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Second operand's numeric text string. The bdigits argument is the address of a descriptor pointing to the second operand's numeric string. The string must be an unsigned decimal number. csign OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Sign of the result. The csign argument is the address of an unsigned longword containing the result's sign. A value of 0 is considered positive; a value of 1 is considered negative. cexp OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Power of 10 by which cdigits is multiplied to get the absolute value of the result. The cexp argument is the address of a signed longword containing this exponent. cdigits OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Result's numeric text string. The cdigits argument is the address of a descriptor pointing to the result's numeric string. The string is an unsigned decimal number. 3 STR$REPLACE The Replace a Substring routine copies a source string to a destination string, replacing part of the string with another string. The substring to be replaced is specified by its starting and ending positions. Format STR$REPLACE destination-string ,source-string ,start-position ,end-position ,replacement-string 4 Corresponding_JSB_Entry_Point STR$REPLACE_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$REPLACE writes the new string created when it replaces the substring. The destination- string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string. The source-string argument is the address of a descriptor pointing to the source string. start-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference for CALL entry point, by value for JSB entry point Position in the source string at which the substring that STR$REPLACE replaces begins. The start-position argument is the address of a signed longword containing the starting position. The position is relative to the start of the source string. end-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference for CALL entry point, by value for JSB entry point Position in the source string at which the substring that STR$REPLACE replaces ends. The end-position argument is the address of a signed longword containing the ending position. The position is relative to the start of the source string. replacement-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Replacement string with which STR$REPLACE replaces the substring. The replacement-string argument is the address of a descriptor pointing to this replacement string. The value of replacement- string must be equal to end-position minus start-position. 3 STR$RIGHT The Extract a Substring of a String routine copies a substring ending at the last character of a source string into a destination string. Format STR$RIGHT destination-string ,source-string ,start-position 4 Corresponding_JSB_Entry_Point STR$RIGHT_R8 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$RIGHT copies the substring. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string from which STR$RIGHT extracts the substring that it copies into the destination string. The source-string argument is the address of a descriptor pointing to the source string. start-position OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference for CALL entry point, by value for JSB entry point Relative position in the source string at which the substring that STR$RIGHT copies starts. The start-position argument is the address of a signed longword containing the starting position. 3 STR$ROUND The Round or Truncate a Decimal String routine rounds or truncates a decimal string to a specified number of significant digits and places the result in another decimal string. Format STR$ROUND places ,flags ,asign ,aexp ,adigits ,csign ,cexp ,cdigits 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments places OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Maximum number of decimal digits that STR$ROUND retains in the result. The places argument is the address of a signed longword containing the number of decimal digits. flags OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference Function flag. A value of 0 indicates that the decimal string is rounded; a value of 1 indicates that it is truncated. The flags argument is the address of an unsigned longword containing this function flag. asign OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Sign of the decimal input string to be rounded or truncated. The asign argument is the address of an unsigned longword string containing this sign. A value of 0 is considered positive; a value of 1 is considered negative. aexp OpenVMS usage:longword_signed type: longword (signed) access: read only mechanism: by reference Power of 10 by which adigits is multiplied to get the absolute value of the decimal input string. The aexp argument is the address of a signed longword containing this exponent. adigits OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Decimal input string. This is the string of digits to which asign and aexp are applied. The adigits argument is the address of a descriptor pointing to this numeric string. The string must be an unsigned decimal number. csign OpenVMS usage:longword_unsigned type: longword (unsigned) access: write only mechanism: by reference Sign of the result. The csign argument is the address of an unsigned longword containing the result's sign. A value of 0 is considered positive; a value of 1 is considered negative. cexp OpenVMS usage:longword_signed type: longword (signed) access: write only mechanism: by reference Power of 10 by which cdigits is multiplied to get the absolute value of the result. The cexp argument is the address of a signed longword containing this exponent. cdigits OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Result's numeric text string. The cdigits argument is the address of a descriptor pointing to this numeric string. The string is an unsigned decimal number. 3 STR$TRANSLATE The Translate Matched Characters routine successively compares each character in a source string to all characters in a match string. If a source character has a match, the destination character is taken from the translate string. Otherwise, STR$TRANSLATE moves the source character to the destination string. Format STR$TRANSLATE destination-string ,source-string ,translation-string ,match-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string. The source-string argument is the address of a descriptor pointing to the source string. translation-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Translate string. The translation-string argument is the address of a descriptor pointing to the translate string. match-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Match string. The match-string argument is the address of a descriptor pointing to the match string. 3 STR$TRIM The Trim Trailing Blanks and Tabs routine copies a source string to a destination string and deletes the trailing blank and tab characters. Format STR$TRIM destination-string ,source-string [,resultant-length] 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$TRIM copies the trimmed string. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string which STR$TRIM trims and then copies into the destination string. The source-string argument is the address of a descriptor pointing to the source string. resultant-length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Number of bytes that STR$TRIM writes into destination-string, not counting padding in the case of a fixed-length string. The resultant-length argument is the address of an unsigned word into which STR$TRIM writes the length of the output string. If the input string is truncated to the size specified in the destination-string description, resultant-length is set to this size. Therefore, resultant-length can always be used by the calling program to access a valid substring of destination- string. 3 STR$UPCASE The Convert String to All Uppercase Characters routine converts a source string to uppercase. Format STR$UPCASE destination-string ,source-string 4 Returns OpenVMS usage:cond_value type: longword (unsigned) access: write only mechanism: by value 4 Arguments destination-string OpenVMS usage:char_string type: character string access: write only mechanism: by descriptor Destination string into which STR$UPCASE writes the string it has converted to uppercase. The destination-string argument is the address of a descriptor pointing to the destination string. source-string OpenVMS usage:char_string type: character string access: read only mechanism: by descriptor Source string that STR$UPCASE converts to uppercase. The source- string argument is the address of a descriptor pointing to the source string.