|
|
|
ALLOCATE_IMMEDIATE indicates an immediate conversation allocation request and that the allocation is conditional upon a session being immediately available. If no session is immediately assigned to the conversation, the allocation fails.
&APPC ALLOCATE_IMMEDIATE has the following format:
&APPC ALLOCATE_IMMEDIATE
TRANSID=transid
[ MODENAME=modename ]
[ SYNC={ NONE | CONFIRM } ]
[ USERID=userid [ PASSWORD=password ] ]
[ PROFILE=profile ]
[ ENV={ CURRENT | DEPENDENT | BACKGROUND } |
LUNAME=luname | LINK=linkname | DOMAIN=domain ]
[ PARMS=(parm1,parm2,...,parmn) |
VARS=var | VARS=(var1, var2, ..., varn ) |
VARS=prefix* [ RANGE=(start,end) ] ]
Operands:
Provides the local transaction identifier for this conversation, as defined in the TCT. If no transaction is known by that identifier, then the allocation fails; otherwise the TCT entry is used to complete details for the allocation. This operand is required.
Nominates the session mode name for the conversation. If omitted, the TCT or OSCT is used to select a default mode name. If present, modename must correspond to a valid mode defined for the APPC link, or the allocation fails.
Specifies the synchronization level for the conversation. If omitted, the TCT is used to nominate the default SYNC level. If SYNC level of NONE is specified, then the following requests cannot be used:
Default: Set by TCT
Specifies the target user ID and, optionally, the password under which the transaction starts on the remote system.
If the transaction being allocated is defined in the TCT with SECURITY=NONE, these operands are ignored.
If the TCT entry is defined with SECURITY=SAME, SECURITY=USERPSWD, or SECURITY=USER, 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.
The ENV operand is the default destination, indicating that the allocation is to take place entirely within the local region of the allocating procedure. If the allocation request came from a remote system, this operand is ignored. Otherwise, the ENV operand specifies the environment where the procedure is attached.
If ENV=CURRENT, or defaulted, the attached target procedure has the same relationship to the allocating procedure as it would have if a START command invokes it.
If ENV=DEPENDENT, the new process is attached in a dependent environment. The process has the same relationship to the allocating procedure as it would have if an &INTCMD START command invokes it.
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.
The LUNAME operand specifies the name of the network LU on which to allocate the remote transaction. When LUNAME is specified, the LINK parameter cannot be used. LUNAME is abbreviated to LU.
If LUNAME=luname is specified, then the target system must be connected to the local system with an APPC link, or must have an appropriate entry in the Dynamic Link Table to permit link initialization. Otherwise, the allocation fails. If luname resolves to the local LU, the conversation proceeds exactly as it would for a remote system, not as described for the ENV parameter. That is, it executes the remote end of the conversation in the appropriate APPC environment within the local system.
The LINK operand nominates the name of the APPC link connecting the local system with the target LU (where you want to allocate the remote transaction). If LINK is specified, then the LUNAME parameter cannot be used. The link must either be active, or be defined in the Dynamic Link Table with an explicit link and LU name (that is, not LUMASK). The definition enables the link to be initialized by the request.
The DOMAIN operand enables identification of the target APPC system by domain name.
The ENV, LUNAME, LINK, and DOMAIN operands are mutually exclusive.
Default: ENV=CURRENT
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.
Alternatively, the VARS operand is used to specify the allocation parameters:
Provides the list of any Program Initialization Parameters (PIP data) to be passed to the transaction processor in the remote end upon initialization of the conversation. Each token implicated by the VARS option is passed as a separate parameter in the PIP subfield list. If the remote conversation partner is an NCL procedure, PIP data is available when the remote procedure is invoked as &1,&2....&n in the usual manner.
Examples: &APPC ALLOCATE_IMMEDIATE
&APPC ALLOCATE_IMMEDIATE TRANSID=DBQUERY
&APPC ALLOCATE_IMMEDIATE TRANSID=DBPUT VARS=DATA
Return Codes:
The request has the following return codes:
Request successful
Request unsuccessful
Remote program error
State check
Request or conversation error
&ZFDBK is 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.
State Transition:
The request is deemed to be performed from reset state, and following successful completion of this request, the conversation enters send state locally. When the remote program or procedure is attached to service the conversation, it is in receive state.
Notes:
Relationship to LU6.2 Verb Set:
&APPC ALLOCATE_IMMEDIATE is equivalent to the LU6.2 verb MC_ALLOCATE with the RETURN_CONTROL(IMMEDIATE) option.
| Copyright © 2009 CA. All rights reserved. |
|