The standard functions contained in PRODAMP can only be called within procedures. The syntax of the function calls corresponds to Pascal syntax.
Function name | Function |
ADDRESS DEC_BINARY DEC_STRING HEX_BINARY HEX_STRING LENGTH LOCATION PATTERN PCK_BINARY | Return the address of a module or control block Convert a decimal string to a numeric variable Decimal editing for printing Convert a hexadecimal string to a numeric variable Hexadecimal editing for printing Output the length of a module, control block or parameter area Return the module name for an address Convert a numeric value to a PATTERN type value Unpack packed numbers from a diagnosis object |
Table 14: Overview of PRODAMP standard functions
The listed names should not be used for user-written procedures, since this may lead to misinterpretation of the program.
ADDRESS
Return address of module or control block
The standard function ADDRESS supplies the address of a module. Consequently, the result variable must be numeric. If the result variable has not yet been initialized, it is assigned the type “numeric” and the length “4”. ADDRESS can also be used to determine relative addresses of fields in a control block.
User program modules can normally only be found in user dumps.
Function call
Operation | Operands |
ADDRESS | (modname, susyname) |
Operands
modname | Specifies the name of the required module. 'modname' may not contain more than 32 characters; however, leading and trailing blanks are permitted before and after the module name. In string types, a distinction is made between uppercase and lowercase notation. modname must therefore be specified in uppercase letters. | |
| susyname | Specifies the subsystem in which the relevant module is to be localized. susyname is a string containing the name of a subsystem or one of the following symbolic names: | |
| CP *PRIV *NONPRIV *USER *ALL | Control Program, i.e. all class 1 and class 2 modules are searched for “modname”. All privileged subsystems are searched for “modname”. All nonprivileged subsystems are searched for “modname”. Only the user CSECTs are searched for “modname”. The entire system is searched for “modname”. | |
If the relative address of a control block is to be determined, modname must contain the field name and susyname must contain the character string “DS”. If the name of a symbol is specified for modname, and if this symbol is the element of a substructure localized by REFERENCE calls, the character string “RF” must be entered for susyname. (For further details see the example for the standard procedure REFERENCE on "Standard procedures".)
Example
A := ADDRESS ('DOPEN', 'CP') ;
MODULE := 'FAUTEM' ;
A := ADDRESS (MODULE, 'ARCHIVE');
A := ADDRESS ('EXVTDSSM','DS');
If the module or symbol is not found, the pseudo-symbol CURRENT.ERROR is given a value î 0. In this case, the returned result is undefined.
DEC_BINARY
Convert decimal number
The standard function DEC_BINARY interprets the contents of a string as a decimal number and returns this number as data of the 4-byte numeric type. Any blanks before and after the relevant characters are ignored.
If the string does not contain a valid decimal value or if the value lies outside the limits for numeric variables, CURRENT.ERROR is set. In this case, the result of DEC_BINARY is undefined.
The enabling of unsigned arithmetic with the standard procedure UNSIGNED_ON is ignored.
Function call
Operation | Operand |
DEC_BINARY | (string); |
Operands
string | String variable that is to be converted. |
DEC_STRING
Convert numeric values
The standard function DEC_STRING converts a specified number into a decimal string. The enabling of unsigned arithmetic with the standard procedure UNSIGNED_ON is ignored.
Function call
Operation | Operands |
DEC_STRING | (number[,length]) |
Operands
number length | Specifies the number that is to be converted. Specifies the length of the string generated. The decimal number is entered in the string right-justified and is padded to the left with blanks. If the specified length is insufficient, leading characters are truncated. If you do not specify a length, only the significant characters are returned (compact format without leading blanks). Exception X := DEC_STRING(I) has the same effect as X := DEC_STRING(I,L), if X is a string variable which has already been initialized with the length L. If you use DEC_STRING without specifying a length for initializing a variable or as a parameter for an expression to be passed to one of your own PRODAMP subroutines, 10 bytes are reserved for the result. In both cases it is better to specify a length explicitly. |
Example
Task: Result: X := 'XXXXXXXX'; —————————————————————————————————————————————————————— (1) X := DEC_STRING (123); ' 123' X := 'XXX'; X := DEC_STRING (123456); '456' —————————————————— (2) X := 'ABC' + DEC_STRING (12) + 'XYZ'; 'ABC12XYZ ' ————— (3) X := 'ABC' + DEC_STRING (12,5) + 'XYZ'; 'ABC 12XYZ' —————————— (4)
(1) | X initialized as an 8-byte string. |
HEX_BINARY
Convert hexadecimal number
The standard function HEX_BINARY interprets the specified string as a hexadecimal number and returns the result as data of the 4-byte numeric type. Any blanks before and after the relevant characters are ignored.
If the string does not contain a valid hexadecimal value or if the value lies outside the limits for numeric variables, CURRENT.ERROR is set. In this case, the result of HEX_BINARY is undefined.
Function call
Operation | Operands |
HEX_BINARY | (string); |
Operands
string | String variable that is to be converted. |
HEX_STRING
Convert numeric values
The standard function HEX_STRING converts a specified number into a hexadecimal string.
Function call
Operation | Operands |
HEX_STRING | (number[,length]) |
Operands
number length | Specifies the number that is to be converted. Specifies the length of the string generated. The hexadecimal number is entered in the string right-justified and is padded to the left with zeros. If the specified length is insufficient, leading characters are truncated. If you do not specify a length, only the significant characters are returned (compact format without leading blanks). In the same way as with DEC_STRING, there are exceptions where no length is specified. Where necessary, the compiler reserves 8 characters for the result of HEX_STRING. | |
Examples
Task: Result: X := 'XXXXXXXX'; X := HEX_STRING (123) '0000007B' X := 'XXX'; "too short" X := HEX_STRING (4097) '001' X not yet initialized X := HEX_STRING (123,8) '0000007B' X not yet initialized X := HEX_STRING (123) '0000007B'
LENGTH
Output length of a module, control block or parameter area
The standard function LENGTH can be called in three variants:
Variant 1: outputs the length of a module
Variant 2: outputs the length of a control block
(DSECT/SPL structure, substructure and field)Variant 3: outputs the length of the parameter area with which the current procedure was called
The result is of type “numeric” and has the length “4”.
Function call
Operation | Operands |
LENGTH | (modname, susyname); |
Operands
modname | Variant 1: | 'modname' is the name of a module, whose length is to be determined. 'modname' can have a maximum of 32 characters, but blanks before or after the module name are allowed. |
| Variant 2: | 'modname' is the name of a control block, whose length is to be determined; maximum 32 characters, but also with additional blanks allowed before or after the name. | |
| Variant 3: | 'modname' is the string '*PARAMETER' | |
susyname | Variant 1: | The name of the subsystem in which the module is to be searched. |
| The following values of the string “susyname” have a special meaning: | ||
| CP *PRIV *NONPRIV *USER *ALL | The control program is searched, i.e. among all Cl1 and Cl2modules. All privileged subsystems are searched. All nonprivileged subsystems are searched. Only the user CSECTs are searched. Everything is searched. | |
| Variant 2: | 'susyname' contains 'DS' or 'RF'. This indicates that the length of the control block or field is to be determined. 'RF' is used in cases where the field is an element of a substructure and used for localizing REFERENCE calls. | |
| Variant 3: | 'susyname' contains 'DS', and “modname” is the string “*PARAMETER”. | |
Notes
The call format LENGTH('*PARAMETER','DS') sets the value of CURRENT.ERROR to 0 and returns the entire length of the parameter area with which the current procedure was called. This length is 0 if the call occurred without parameters.
Examples for the use of LENGTH('*PARAMETER','DS') can be found starting on "Pseudo-structures".
When LENGTH is called for a module or control block, a subsequent examination of CURRENT.ERROR should indicate whether or not this module or control block was actually found.
This allows you to check for the existence of a control block field in the currently loaded symbol elements before a symbolic access with that control block field and to respond accordingly.
Examples
L:=LENGTH('NCTVXVT','CP');
L:=LENGTH('EXVT','DS');
L:=LENGTH('EXVTPRD','DS');
L:=LENGTH('*PARAMETER','DS');
L:=LENGTH('MYDSECT','DS');
IF CURRENT.ERROR <> 0 THEN
" Error case; continue by dynamically loading required symbols via "
" COMMAND ('ADD-SYMBOLS ...'), for example, or error exit "
END IF;
LOCATION
Return module name for address
The standard function LOCATION returns the name of the module in which the specified module name is located. Consequently, the result must be assigned to a string variable.
The module name is transferred in 32 characters at the most. If the string variable is too short to accommodate the module name, it is truncated. If it is longer than the module name, the remaining space is filled with blanks. If the target variable has not yet been initialized, it is assigned the type “string” and the length “8”.
If the specified expression does not match any address from a system module, LOCATION sets the pseudo-symbol CURRENT.ERROR. If the address is found in user memory, the target variable receives the value “ABSOLUTE”; if not, it receives the value “?”.
The displacement of this module from the start of the module can then be determined with the aid of the standard function ADDRESS.
Function call
Operation | Operands |
LOCATION | (address, susyname); |
Operands
address susyname | Address of the module that is to be localized. Subsystem in which the module is to be localized. susyname is a string that contains either the name of the subsystem or one of the following symbolic identifiers: | |||
CP | The control program is searched, i.e. among all Cl1 and Cl2 modules. | |||
Example
NAM := LOCATION ( ADDR, 'CP' ); REL := ADDR - ADDRESS ( NAM, 'CP' ) ;
PATTERN
Convert numeric value
The PATTERN function converts a numeric value to a value of the type PATTERN. If the result variable does not exist, it is assigned a length of 4 bytes.
A conversion of this type is required if, for instance, a loop is to be used to check data to see whether certain bits are set or not. Since no operations are available which, for instance, produce the value P'02' from P'01', this can only be done by converting numeric values.
Function call
Operation | Operands |
PATTERN | (num) |
Operands
num | Specifies the numeric value to be converted. |
Example
L := 1;
U := 1;
WHILE L < 8 DO
IF PATTERN ( U ) IN .EXVTULM THEN
.......
.......
END IF;
U := U * 2;
L := L + 1;
END WHILE;
PCK_BINARY
Unpack packed numbers
PCK_BINARY converts packed numbers into unpacked numbers. The result is numeric and has the length “4”.
If the string does not contain a packed number, CURRENT.ERROR is set.
Function call
Operation | Operand |
PCK_BINARY | (string) |
Operands
string | Specifies the number that is to be unpacked. |