|
|
|
&APPC START allows the calling procedure to start a new NCL process in either the same or any connected APPC system.
As part of the start request, the initiating procedure can pass any number of NCL variables, MDOs, or both, which are copied and created in the context of the new process. The initiating procedure can issue the request and continue processing without any indication that the new process has started. The procedure can also specify that the request not complete until the new process has successfully started, or failed to start.
This verb has the following format:
&APPC START
PROC=proc
[ SERVER=servername
[ SCOPE={ REGION | USER | SYSTEM } ] ]
[ ENV={ CURRENT | DEPENDENT | BACKGROUND } |
LUNAME=luname | LINK=linkname | DOMAIN=domain ]
[ USERID=userid [ PASSWORD=password ] ]
[ PROFILE=profile ]
[ NOTIFY={ NO | YES } ]
[ VARS=(genvars1,genvars2,...,genvarsn) ]
[ PARMS=(parm1,parm2,...,parmn) ]
Operands:
Specifies the name of the NCL procedure to start.
Specifies the logical name for this NCL process. The name must be up to 32 characters long and unique within the scope as determined by the SCOPE operand, or the request fails.
Provides the scope for the registration of servername (which must be unique within the scope indicated) and is valid only if the SERVER operand is present. Valid scopes are:
Indicates that servername is to be unique within the current session, as defined by a particular connection to your product region.
Indicates that servername is to be unique across all sessions associated with the particular user ID
Indicates that servername is to be unique within this product region.
Specifies where to initiate the started procedure.
If ENV=CURRENT (or defaulted), the new process starts as a peer of the requesting process.
If ENV=DEPENDENT, the new process starts as a dependent of the requesting process. If either the USERID or PROFILE operand is present, and specifies a user other than the requesting user ID, the ENV operand is ignored. The new process is started in the APPC region for the target user ID.
If ENV=BACKGROUND, the new process is attached in the background APPC server region for the requesting user ID, as if the request was sourced from a remote system.
With one of the following parameters, the new process is always started in the APPC region for the target user on the indicated APPC system:
If an existing APPC region for the target user does not exist, one is created through this function.
This behavior is true even where LUNAME=luname is used to specify the local system, and hence behaves differently from the use of the ENV operand.
If the DOMAIN operand is used but the APPC system cannot be located by domain name, the request fails. For example, an INMC link has not been activated to the system and therefore the domain is unknown.
Specifies an alternate user ID and, optionally, the password, under which this process is to start. The security exit in the target system verifies the user ID and password before the new process is initiated.
The START 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 whether synchronization with the start of the new process is required. If NOTIFY=NO is specified (or defaulted), no information is returned to the user regarding whether the new process started successfully or not. If NOTIFY=YES is specified, the &APPC START request does not complete until the new process has been loaded and is about to commence execution. In addition, the NCL ID and domain of the started process is returned to &SYSMSG.
Specifies the set of NCL variables, MDOs, or both to pass to the started process. In the new process, a copy of each variable or MDO is created with the same name and value.
The data following the VARS operands is a single value, or a list of one or more values enclosed in parentheses. 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 was coded.
A single MDO is referenced by including its entire name followed by a full stop. For example, an entry in the list of XYZ. refers to the single MDO named XYZ, as though MDO=XYZ was coded.
A range of variables is referenced by including a name prefix followed by an asterisk. For example, an entry in the list of $CNM* refers to all variables with names beginning with $CNM, as though VARS=$CNM was coded.
A specific range of variables is referenced by including a name prefix followed by an asterisk, and the range in parentheses. For example, an entry in the list of UVW*(1,10) refers to the range of variables &UVW1 through &UVW10 as if VARS=UVW RANGE=(1,10) was coded.
A numeric range of variables is referenced by including a name prefix followed by an asterisk. For example, an entry in the list of $CNM* refers to all variables with names of the form $CNMn, where n is a numeric suffix. All such variables are located, unless a specific range is coded (for example, $CNM*(1,20)). A generic range of variables is referenced by including a name prefix, followed by >. For example, A> refers to all tokens beginning with A, plus all MDOs beginning with A.
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.
Example: & APPC START
&APPC START PROC=POSTMAN PARMS=(&USERID,&MAILMSG)
Return Codes:
The return codes are as follows:
Accepted
Transaction error (&SYSMSG is set)
OK (&SYSMSG contains N23Q01)
Start failed (&SYSMSG contains N23Q03)
Transaction error (&SYSMSG is set)
N23Q01 indicates process start. N23Q03 indicates process failure. Both messages carry the NCL ID and domain where the process was created.
| Copyright © 2011 CA. All rights reserved. | Tell Technical Publications how we can improve this information |