INCLUDE-PROCEDURE Start command sequence as include procedure

Domain: PROCEDURE

Command description

An include procedure is a procedure which is visible in the data environment of the calling procedure. This means that all variables visible in the calling procedure are visible in the include procedure. However, a variable in the calling procedure can be overlaid by a new declaration in the include procedure (see example).

The INCLUDE-PROCEDURE command starts a stored command sequence (procedure). During processing, symbolic parameters contained in the sequence are replaced by the values specified in the command call (PROCEDURE-PARAMETERS operand).

• Current parameters may be transferred as variables; these are also used by the procedure to return output values.

• Current parameters may be transferred as positional parameters or as keyword parameters. The sequence of positional parameters corresponds to the dynamic sequence of the DECLARE-PARAMETER commands; the names of keywords correspond to the names of formal procedure parameters. Keywords may be abbreviated as long as they remain unequivocal.

• Logging is set in the command call; the same applies to the specification regardless of whether or not an already loaded program may be unloaded.

Procedures can be stored as:

• a cataloged SAM or ISAM file (even a temporary one) with records of variable length

• a type J or SYSJ element in a PLAM library

• an S variable of the “list” type

Procedure formats:

• text procedure
  The S procedure is in its original text format. The full SDF-P functionality is available only if the chargeable SDF-P subsystem is loaded when the procedure is called. In libraries, element type J should be used for text procedures.

• object procedure
  An S procedure in text format has been translated to object format with the COMPILE-PROCEDURE command. An object procedure can utilize the full functionality of SDF-P (apart from the COMPILE-PROCEDURE command) regardless of whether or not the SDF-P subsystem is currently available. In libraries, element type SYSJ (the default for COMPILE-PROCEDURE) should be used for object procedures.

Format

INCLUDE-PROCEDURE                                     Alias: INP

FROM-FILE = <filename 1..54 without-gen> / *LIBRARY-ELEMENT(...) / *VARIABLE(...)

*LIBRARY-ELEMENT(...)

LIBRARY = <filename 1..54 without-gen>

,ELEMENT = <composed-name 1..64>(...)

<composed-name 1..64>(...)

VERSION = *HIGHEST-EXISTING / <composed-name 1..24>

,TYPE = *STD / *BY-LATEST-MODIFICATION / <alphanum-name 1..8>

*VARIABLE(...)

VARIABLE-NAME = <composed-name 1..255>

,PROCEDURE-PARAMETERS = *NO / <text 0..1800 with-low expr>

,LOGGING = *PARAMETERS(...) / YES / *NO /

*PARAMETERS(...)

CMD = *BY-PROC-TEST-OPTION / *YES / *NO

,DATA = *BY-PROC-TEST-OPTION / *YES / *NO

,UNLOAD-ALLOWED = *YES / *NO

,EXECUTION = *YES / *NO

Operands

FROM-FILE = <filename 1..54 without-gen> / *LIBRARY-ELEMENT(...) / *VARIABLE(...)
Name of the procedure file.

FROM-FILE = *LIBRARY-ELEMENT(...)
The procedure is stored in a PLAM library.

LIBRARY = <filename 1..54 without-gen>
Name of the PLAM library containing the procedure as an element (type J or SYSJ; see the TYPE operand).

ELEMENT = <composed-name 1..64>(...)
Name of the element.

VERSION = *HIGHEST-EXISTING / <composed-name 1..24>
Version of the library element. The default value is HIGHEST-EXISTING, i.e. the procedure is taken from the element with the highest version.

TYPE = *STD / *BY-LATEST-MODIFICATION / <alphanum-name 1..8>
Designates the element type the procedure file is stored under in the PLAM library.

TYPE = *STD
The procedure file can be stored as an element of type SYSJ or J.
The specified element is first searched for among the type SYSJ elements.If it is not found there, the search proceeds to the type J elements.

A non-S procedure can only be a type J element.
An S procedure may be either a text procedure (original text format) or an object procedure (compiled object format). To simplify maintenance of the two formats in a library, text procedures should be stored as type J elements, object procedures as type SYSJ elements. The COMPILE-PROCEDURE command by default generates an object procedure of type SYSJ (default) from a text procedure of type J.
If this convention is followed, specifying TYPE=*STD (the default value) ensures that object procedures will be given precedence over text procedures.

TYPE = *BY-LATEST-MODIFICATION
The procedure file can be stored as an element of type SYSJ or J.
If the specified element exists both as type SYSJ and as type J, the element most recently modified will be called. If the time stamp is identical, the type SYSJ element will be called.
Specifying TYPE=*BY-LATEST-MODIFICATION ensures that the most up-to-date element will be called, typically during the debugging phase when a procedure is being written or modified.

TYPE = <alphanum-name 1..8>
The procedure file will be searched among elements of the specified type only.

FROM-FILE = *VARIABLE(...)
The procedure is stored in an S variable of the “list” type.

VARIABLE-NAME = <composed-name 1..255>
Name of the S variable.

PROCEDURE-PARAMETERS = *NO / <text 0..1800 with-low expr>
Defines the current procedure parameters; the parameters must be enclosed in parentheses.
See section “Passing procedure parameters” for more details about procedure parameters.

LOGGING = *PARAMETERS(...) / *YES / *NO
This controls logging of procedure execution.
The LOGGING operand is ignored when non-S procedures are called, since in this case logging can only be declared in the procedure head (see the LOGGING operand in the BEGIN-PROCEDURE command).
When an S procedure is logged, every procedure line that is processed is output with the line number and procedure level prefixed to it.

See section “Setting the logging” for more details about logging.

LOGGING = *PARAMETERS(...)
Logging can be set separately for command/statement lines and for data lines.

CMD = *BY-PROC-TEST-OPTION / *YES / *NO
This specifies whether commands are to be logged. The default value is BY-PROC-TEST-OPTION, i.e. no logging (equivalent to *NO) or the value selected as the default by the user with the MODIFY-PROC-TEST-OPTIONS command.

DATA = *BY-PROC-TEST-OPTION / *YES / *NO
This specifies whether data lines are to be logged. The default value is BY-PROC-TEST-OPTION, i.e. no logging (equivalent to *NO) or the value selected as the default by the user with the MODIFY-PROC-TEST-OPTIONS command.

UNLOAD-ALLOWED = *YES / *NO
This specifies whether a program that was loaded when the procedure was called may be unloaded.
Protection against unloading is guaranteed only for unloading by means of the commands START-EXECUTABLE-PROGRAM, LOAD-EXECUTABLE-PROGRAM and CANCEL-PROGRAM.
The specification YES is ignored if the procedure is called from a procedure for which UNLOAD-ALLOWED=*NO was declared.

EXECUTION = *YES / *NO
This specifies whether the procedure is merely to be analyzed for test purposes or whether it is also to be executed.
Testing is possible via the MODE operand of the MODIFY-SDF-OPTIONS command.

Command return codes

The following command return codes can only be returned if the called procedure does not supply any command return code itself (e.g. EXIT-PROCEDURE not executed due to an error).

Command return codes whose maincode begins with “SSM” can only be returned when a non-S procedure is called.

Command return codes whose maincode begins with “SDP” can only be returned when an S procedure is called.

(SC2)	SC1	Maincode	Meaning
	0	CMD0001	No error
2	0	SSM2058	Protocol type error
2	0	SSM2065	EOF on procedure file, /END-PROC simulated
	1	SSM2036	Incomplete operand
	1	SSM2054	Symbolic operand error
	1	SSM2055	Symbolic operand error in /BEGIN-PROC
	1	SDP0138	Error in pre-analysis of text procedure, or object procedure invalid
	1	CMD0202	Syntax error
	3	CMD2203	Incorrect syntax file
	32	CMD0221	System error (internal error)
	64	SDP0093	Non-S procedure can only be type J element
	64	SDP0144	Error on parameter transfer
	64	SSM2052	DMS error (Open error)
	64	SSM2053	Not a SAM/ISAM file or file does not begin with /BEGIN-PROC or /PROC
	64	SSM2056	/CALL-PROC and /BEGIN-PROC parameters incompatible
	64	SSM2061	Error on accessing library element
	64	SSM2064	Procedure file cannot be fetched by remote processor
	130	SDP0099	No further address space available
xx	xx	xxxxxxx	Other return codes from the called procedure

Example

Procedure 1:

/DECLARE-VARIABLE A(TYPE = *STRING)
/DECLARE-VARIABLE B(TYPE = *STRING)
/DECLARE-VARIABLE C(TYPE = *STRING)
/DECLARE-VARIABLE D
/INCLUDE-PROCEDURE PROC2

Procedure PROC2:

/DECLARE-VARIABLE NAME=A(INIT-VALUE=1,TYPE=*INTEGER),SCOPE =*CURRENT ——  (1) 
/DECLARE-VARIABLE NAME=C(TYPE=*STRING),SCOPE = *PROCEDURE  ————————————  (2) 
/DECLARE-VARIABLE NAME=B(TYPE=*INTEGER),SCOPE = *PROCEDURE ————————————  (3) 

(1)	A variable A, which is valid only in PROC2 is declared in PROC2. Variable A in the calling procedure (Procedure 1) is therefore not visible in PROC2, but only after PROC2 is terminated.
(2)	This is a permissible multiple declaration. It is ignored. The procedure variables C and D in Procedure 1 are visible in PROC2. The procedure variable A in Procedure 1 is covered by variable A in PROC2.
(3)	ERROR: The third declaration produces an error, because a procedure variable B having another data type already exists. In a multiple declaration, all attributes must match the original declaration.