|
|
|
&APPC RPC allows the calling procedure to call an NCL procedure in either the same or any connected APPC system.
As part of the remote procedure call, the initiating procedure can pass any number of NCL variables, MDOs, or both, as shared variables, to be presented in the context of the new process.
This verb has the following format:
&APPC RPC
PROC=procname
[ LUNAME=luname | LINK=linkname | DOMAIN=domain ]
[ USERID=userid [ PASSWORD=password ] ]
[ PROFILE=profile ]
[ SHARE | SHARE=(shrvars1,shrvars2,...,shrvarsn) |
NOSHARE=(shrvars1,shrvars2,...,shrvarsn) ]
[ RETCODE=varname ]
[ PARMS=(parm1,parm2,...,parmn) ]
Operands:
(Mandatory) Specifies the NCL procedure to call.
Specifies where the procedure executes.
Specifies an alternate user ID and, optionally, the password, under which this process starts. The security exit on the target system verifies the user ID and password before the new process is initiated.
The RPC system transaction uses SECURITY=SAME processing. Therefore, APPC includes the supplied user ID and password in the attach header for validation on the remote system.
If the user ID is specified with no password, the user ID is included in the attach header. The already verified indicator is not set unless the user ID is that of the requesting user environment. However, for a same LU transaction, APPC performs lock and key processing to determine whether the target user ID is signed on by the requester.
Note: For more information about APPC security, see the Network Control Language Programming Guide.
Specifies the profile name to place in the attach header access security fields. If omitted, no profile is used. APPC makes no use of the PROFILE operand.
Specifies the set of NCL variables, and/or MDOs, to be shared or not shared with the called procedure.
If the SHARE or NOSHARE operands are omitted, no variable sharing occurs for this call. If the SHARE keyword is coded without parameters, the current &CONTROL SHRVARS (or NOSHRVARS) setting is used for the call.
If the SHARE or NOSHARE keyword is used with parameters, any current &CONTROL SHRVARS settings are ignored for this execution. When SHARE is used the called procedure obtains a copy of each variable, and/or MDO, referenced by the SHARE operand. When NOSHARE is used, the called procedure obtains a copy of all NCL variables and MDO data not specified by the operand.
The parameter values for SHARE and NOSHARE cannot be substituted on the statement.
The operand can specify a single value or a list of values. Each item in the list can reference a single variable or MDO, or multiple variables or MDOs. A single variable is referenced by including its entire name. For example, an entry in the list of 'ABC' refers to the single NCL variable &ABC, as though VARS=ABC were coded. A single MDO is referenced by including its entire name followed by a full stop. For example, an entry in the list of 'ABC.' refers to the single MDO named ABC, as though MDO=ABC were coded.
A range of NCL variables is referenced by including a name prefix followed by an asterisk. For example, an entry in the list of '$CNM*' refers to $CNM1...$CNMnnn. The range is set explicitly, for example, '$CNM*(1,10)' (or '$CNM(1,10)') refers to the variables $CNM1 to $CNM10. If not set explicitly, all variables of the form $CNMnnn are assumed.
A generic list of NCL variables and MDOs is referenced by including a name prefix followed by a > symbol. For example, an entry in the list of '$NW>' refers to all variables, and MDOs, with names beginning with &$NW.
Specifies the name of a local NCL variable that contains the &RETCODE value from the called procedure.
Specifies a list of parameters to pass to the procedure. Parentheses enclose the parameter list, and a comma separates each pair of parameters.
The parameter list can contain any combination of characters, including variables. The first parameter isolated is placed in &1 in the target procedure, the next in &2, and so on. The list is analyzed before substitution occurs and each parameter is isolated, by scanning for a comma or the closing parenthesis. If another opening parenthesis is encountered, a syntax error results. If a single or double quote is encountered as the first character of a parameter, the entire parameter is assumed to be quoted. Otherwise, it is treated as unquoted. If an unquoted parameter is encountered, the next comma or closing parenthesis delimits it. Any other characters are considered part of the parameter itself.
Once isolated, substitution is performed, if necessary (allowing transparent data to be passed as parameters). The result is placed in the next initialization parameter in the called procedure.
A closing quote of the same type as the opening quote terminates a quoted parameter. Only a comma delimiting the next parameter, or a closing parenthesis terminating the entire parameter list, can immediately follow the closing quote. The entire quoted string is passed to the target procedure unchanged, except that the delimiting quotes are removed.
Normal quote rules apply. That is, two consecutive quotes of the same type as the opening quote are treated as a single occurrence in the resulting string. No substitution is performed on the contents of the quoted string.
For example:
PARMS=(&USER,,PROC=&0,“variable ““&FRED”” in error”)
The example sets the following variables in the called procedure (assume &USER has the value 'ADMIN', &0 'MYPROC', and &FRED 'xyz'):
&1 ADMIN &2 &3 PROC=MYPROC &4 variable “&FRED” in error
&RETCODE or &END in the called procedure sets the return codes.
If used, the PARMS operand must be the last operand on the &APPC statement.
Examples: &APPC RPC
&APPC RPC PROC=SHOWUSER PARMS=(ABC)
Return Codes:
The return codes are as follows:
Request successful
Remote program error
Request or conversation error
&ZFDBK is also set, plus all APPC system variables.
This request sets the system variable &ZAPPCID, which returns the system conversation identifier allocated to the conversation. This value is saved and supplied on the ID operand of subsequent &APPC requests to nominate a specific conversation where the NCL process is operating more than one conversation concurrently.
| Copyright © 2011 CA. All rights reserved. | Tell Technical Publications how we can improve this information |