ICF Files, EVOKE

Use this file- or record-level keyword to start a program on the remote system.

The format of the keyword is:

EVOKE([library-/e1e/]program-name [parameter-1...[parameter-255]])

The program-name can be any one of the following:

program-name: This is the name of the program to be started on the remote system. The name is syntax-checked at creation time for a valid object name.
'character-string-1': This is the name of the program to be started on the remote system. The name you specify must be in a format acceptable to the remote system because the character string will not be syntax-checked.
&field-name-1: The specified field contains the name of the program to be started on the remote system. The field name must be a valid field you have specified in the record format and must be a character field (data type of A). The name you specify must be in a format acceptable to the remote system.

The optional library-name can be any one of the following:

library-name/: This is the name of the library that contains the program to be started on the remote system. The name is syntax-checked at creation time for a valid object name. For this keyword, *CURLIB and *LIBL are not valid names. If either one needs to be specified, a quoted character string should be used.
'character-string-2'/: This is the name of the library that contains the program to be started on the remote system. The name you specify must be in a format acceptable to the remote system because the character string will not be syntax-checked.
&field-name-2/: The specified field contains the name of the library that contains the program to be started on the remote system. The field name must be a valid field you have specified in the record format and must be a character field (data type of A). The name you specify must be in a format acceptable to the remote system.

Note: If the remote system is an iSeries™ server and no library was specified, the library list will be used to search for the program.

Parameter-1 through parameter-255 can be any of the following:

'character-string-3': This is a character string that is passed to the program on the remote system. The character string must be in a format acceptable to the remote system because it will not be syntax-checked.
[&]field-name-3: This is the name of the field that contains the data you want passed to the program on the remote system. The field name must be a valid field you have specified in the record format.
numeric-value-3: This is a numeric value that is passed to the program on the remote system. The numeric value can be a negative or positive value (signed or unsigned). A decimal point of , or . is optional. No decimal alignment will be performed. Leading zeros will not be suppressed. The data is sent as a zoned decimal value. The following numeric values are all valid:

999.6
-999,6
01587

Special considerations when using the EVOKE keyword with ICF files

These are special considerations when using the EVOKE keyword.

When the EVOKE keyword is specified at the file level, you cannot specify a field name as a parameter value.
The maximum length allowed for the combined program name and library name is 64. The slash between the program name and the library name is counted as part of the 64 bytes. Advanced Program-to-Program Communication (APPC) does not send the slash unless it is specified within a literal (for example, LIBRARY/PROGRAM).
The total length of parameter-1 through parameter-255 cannot be more than 32 767 bytes.
Note: In calculating the maximum length of PIP data for APPC, keep these considerations in mind:
Four bytes must be added to the length of each of these parameters. An additional 4 bytes must be added if any parameters are specified. These bytes are required by the system.

Use the following formula to determine the total length of the parameters:

4 + (length of 1st parameter + 4) + (length of
2nd parameter + 4)
+ ... (length of nth parameter + 4)

Here is an example of how to use this formula:

EVOKE(LIBRARY1/PROGRAM1 'THIS IS AN EXAMPLE OF
A
CHARACTER STRING' &FIELD1 35)

Assume that &FIELD1 has a length of 10.
4 + (40 + 4) + (10 + 4) + (2 + 4) = 68
The length of each parameter (parameter-1 through parameter-255) should be the same as the length of the corresponding parameter in the remote program.
If a field name with a usage of P is specified as a parameter of the EVOKE keyword, this field is not sent as part of the data record.
A program evoked on an iSeries server will receive any parameters sent by the remote program just as if they had been passed by the CL CALL command.
Note: If the job on the iSeries server is a prestart job, the program must use the RTVDTAARA command to receive the parameters.

This keyword is required when either the SECURITY or SYNLVL keyword is specified. At run time, the SECURITY and SYNLVL keywords are used only when EVOKE is also in effect.

The EVOKE keyword is ignored at run time when CANCEL, CNLINVITE, EOS, FAIL, NEGRSP, RSPCONFIRM, or RQSWRT is in effect. These keywords must have option indicators when they apply to a record for which the EVOKE keyword applies. If a CANCEL, CNLINVITE, EOS, FAIL, NEGRSP, or RQSWRT keyword with no option indicator applies to a record for which EVOKE applies, an error message is issued and the EVOKE keyword is ignored at creation time.

You cannot specify EVOKE with the TIMER keyword.

Option indicators are valid for this keyword and are required if this keyword is specified more than once for each record format or file.

Example

The following example shows how to specify the EVOKE keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A          R RCD
00020A  01        :                         EVOKE(LIBRARY1/PROGRAM1)   (1)
00030A  02        :                         EVOKE(LIBRARY2/PROGRAM2)   (1)
     A            :                          :
     A            :                          :
00090A          R RCD2                      EVOKE(&FIELD2/&FIELD1 'ABC' 10.1 +
00100A                                      FIELD3)            (2)
00110A            FIELD1        10A  P
00120A            FIELD2        10A  P
00130A            FIELD3         5B  P
     A

Note:

(1): If indicator 01 is on, PROGRAM1 in LIBRARY1 will be started. If indicator 02 is on, PROGRAM2 in LIBRARY2 will be started.
(2): &FIELD1 contains the name of the program to be started. &FIELD2 contains the name of the library. The character string ABC, numeric value 10.1, and the value in FIELD3 will be passed to the program on the remote system.

EVOKE (Evoke) keyword for ICF files

Special considerations when using the EVOKE keyword with ICF files

Example