DDS Reference: ICF Files
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...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 are all valid numeric values:
999.6
-999,6
01587
Special considerations when using the EVOKE keyword with ICF
files
The following 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. 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, the following must be
considered:
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)
Following is an example using 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 keywords are
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
- (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.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.