|
|
|
&ASSIGN sets the data values of a list or range of variables from another list or range, or a data constant.
&ASSIGN updates lists or ranges of variables in one operation. &ASSIGN is used to copy data between variables, update variable attributes, and determine the names of variables flagged as MODFLDs.
The &ASSIGN options allow the actual structure of an MDO, or its structure according to the map, to be derived during NCL execution. All MDO query functions must use tokens as the target for the information to be returned.
&ASSIGN manipulates multiple variables in one operation. The default function, OPT=DATA, is used to assign values to a target list or range of variable names from the values of a string of data, or a source list, or a range of variables. If no source data is provided or exists, then the target variable is set to nulls.
OPT=MODFLD uses the names of variables, flagged as modified fields, as the source data and extends the use of the &ZMODFLD built-in function.
The SETERR, SETMOD, RESETERR, and RESETMOD functions provide the ability to update the attributes of the target variables. The SETOUT and RESETOUT functions provide the ability to set or reset the output attribute on the target variables.
The maximum number of variables (range limit) that &ASSIGN can create in one operation is governed by the &CONTROL RNGLIM | NORNGLIM operand. If this is set to RNGLIM, then the range limit is 64. If very large numbers of variables are to be processed in one operation, then use NORNGLIM (the default value of this operand) to remove the limit of 64.
This verb has the following formats.
To set the data values of a list or range of variables from another list or range, or a data constant:
&ASSIGN [ OPT= DATA ]
{ VARS={ name | ( name, name, ..., name ) } |
VARS=prefix* [ RANGE=( start, end ) ] |
GENERIC | REPLACE | ADD | UPDATE |
ARGS [ [ RANGE=( start, end ) ] | MDO=aaa.bbb.ccc |
MDO=aaa.bbb.ccc.* | MDO=aaa.bbb[*].ccc |
MDO=aaa [ MAP=map ] ] }
[ DATA=value |
FROM { VARS={ name | ( name, name, ..., name ) } |
VARS=prefix* [ RANGE=( start, end ) | GENERIC ] |
ARGS [ RANGE=( start, end ) ] |
MDO=aaa.bbb.ccc | MDO=aaa }
MDO=aaa.bbb.ccc.* | MDO=aaa.bbb[*].ccc ]
To set a list or range of variables to the names of MODFLD variables:
&ASSIGN OPT= MODFLD [ NONULLS | NORESET ]
{ VARS={ name | ( name, name, ..., name ) } |
VARS=prefix* [ RANGE=( start, end ) ] |
ARGS [ RANGE=( start, end ) ] }
[ FROM { VARS=[ name | ( name, name, ..., name ) ] |
VARS=prefix* [ RANGE=( start, end ) | GENERIC ] |
ARGS [ RANGE=( start, end) ] } ]
To update the attributes of a list or range of variables:
&ASSIGN OPT={ SETERR | RESETERR | SETMOD | RESETMOD }
{ VARS={ name | ( name, name, ..., name ) } |
VARS=prefix* [ RANGE=( start, end ) ] |
ARGS [ RANGE=( start, end ) ] }
To set or reset the output attribute on the specified target variable:
&ASSIGN OPT={ SETOUT | RESETOUT }
{ VARS={ name | ( name, name, ..., name ) } |
VARS=prefix* [ RANGE=( start, end ) ] |
ARGS [ RANGE=( start, end ) ] }
The &ASSIGN syntax for querying MDO and map names:
&ASSIGN OPT={ NAMES,TAGS,TYPES,LENGTHS,#ITEMS,NAMEDVALUES }
{ VARS=( aaa, bbb, ..., ccc ) |
VARS=aaa* [ RANGE=( start, end ) ] |
ARGS [ RANGE=( start, end ) ] }
[ FROM | DEFINED_IN | PRESENT_IN | MANDATORY
{ MDO=aaa | MDO=aaa.bbb.ccc }]
Operands:
If specified, the OPT keyword changes the nominated attribute of the target variables. The following options are available:
(Default option) Specifies that the &ASSIGN operation is to transfer the contents of source variables or data constant (as supplied by the FROM specification) to the target variables. If either a DATA= or a FROM option is not specified, then target variables are set to null.
Specifies that the values that the target variables are to receive are the names of variables updated as MODFLDs by certain NCL verbs, such as &PANEL and &NDBGET. If only one target variable is supplied, then this function is equivalent to referencing the &ZMODFLD system variable. If source variables are specified by using the FROM option, then only these variables are scanned as MODFLDs. Enough names are used to exhaust the target list or range. Remaining target variables are set to null.
Variables flagged as MODFLDs by panel operations are returned in the order in which they appear on-screen, that is, line-by-line from top-left to bottom-right. The order for MODFLD variables returned by &NDBGET is unspecified.
For OPT=MODFLD the following options are supported:
Specifies that null variables are not used to satisfy the MODFLD option. The target variables assigned by the MODFLD operation therefore do not contain the names of null variables.
Specifies that source variables are not to have the MODFLD attribute reset once the MODFLD operation is completed. The default resets the MODFLD attribute to prevent it being selected further by either &ZMODFLD or &ASSIGN.
Specifies that target variables are to be given the ERRFLD attribute if displayed on a panel. No source variables are associated with this operation.
Specifies that target variables are to have the ERRFLD attribute reset. No source variables are associated with this operation.
Specifies that target variables are to be given the MODIFIED attribute. If displayed on a subsequent panel, these variables appear to the procedure to have been modified even if not modified by the user. No source variables are associated with this operation.
Specifies that the MODIFIED attribute is to be reset for the target variables. If variables are displayed on a panel, then these do not appear as modified fields on subsequent input, unless they have been modified on the panel. No source variables are associated with this operation.
Specifies that the target variables are to be assigned the output attribute. This attribute indicates that if the name appears in an input field, it is protected and displayed as an output field.
Specifies that the target variables are to have the OUTPUT attribute reset.
The OUTPUT attribute affects panels displayed by procedures running with the &CONTROL FLDCTL option. This attribute is reset on all variables after a panel is displayed even if the variable did not appear on the panel.
When you switch a field from INPUT to OUTVAR using this method, the field attributes (for example, color and extended highlighting) may not be suitable for the output field. The ***UNDOCUMENTED*** standard input attributes are tested against the attributes of the field being altered. If the field has the same attributes as the standard input low intensity field, it is given the attributes of the standard low intensity output field. Likewise for the high intensity field attributes. If the field attributes do not match either standard, then the field is only protected, and no other attribute is changed.
Applies to PRESENT_IN, DEFINED_IN, and MANDATORY options, and returns the component names associated with the target MDO name, as follows:
If only an MDO stem name is specified (for example, MDO=abc), then the name of the currently connected map is returned as the defined component name on this query, but only if the MDO exists.
If the MDO name is a compound name (for example, MDO=a.b.c), then the name of the last component in the name list (that is, c) is returned, depending upon the PRESENT_IN, DEFINED_IN, or MANDATORY option.
If the MDO name is a compound generic name (for example, MDO=a.b.c.*), then multiple names may be returned, where each name returned is a sub-component of the nominated component (for example, for MDO=a.b.c.*, all x where x is a component defined within c). This is useful for determining the names of all components that are either present in, or defined within, a given structure. It is also useful for determining which component is within a structure that is a CHOICE type.
Note: For SEQUENCE OF and SET OF items, it is possible to have null-named components, as the SEQUENCE or SET OF items are processed by index value only.
A compound variable indexed name (for example, MDO=a.b{*}.c, or MDO=a.b.{*}) is not supported on this query.
Applies to PRESENT_IN, DEFINED_IN, and MANDATORY options and returns the component tags used by Mapping Services associated with the target MDO name. Component selection is as for OPT=NAMES.
Applies to PRESENT_IN, DEFINED_IN, and MANDATORY options and returns the component type defined within the map and associated with the target MDO name. Component selection is as for OPT=NAMES.
Applies only when PRESENT_IN is specified and returns the local form data length within the MDO of the target components. Component selection is as for OPT=NAMES.
Applies only when PRESENT_IN is specified, and returns the number of items within a nominated component as follows:
If the MDO name is a stem name (for example, MDO=stem), or a compound name (for example, MDO=a.b.c), then a count of 0 is returned if the component does not exist; otherwise it is 1.
If the MDO name is a compound generic name (for example, MDO=a.b.c.*), then a count of 0 is returned if the nominated component a.b.c is in one of the following conditions:
Applies to components that have named values associated with their type. These types are limited to BIT STRING, INTEGER, and ENUMERATED. Other types return null results. No generic indexes or generic names are allowed on this option.
If DEFINED_IN is specified, then a list of the named values defined in the map for the specified component is returned.
PRESENT_IN is invalid for OPT=NAMEDVALUES.
Applies to string types that can have their character set constrained to particular characters or strings. It only works in conjunction with the DEFINED keyword. If a string type (for example, GraphicString) has been constrained to a particular set of characters or strings, then this option returns the valid characters or strings in the target variable. If there are no constraints, then no values are returned on assignment. The &ZVARCNT system variable is set to indicate the number of target variables set by the assignment.
Example:
If there is a component defined as follows:
datax GraphicString (“ABCD” | “xyz” | “QQQ” )
then &ASSIGN VARS=X* OPT=VALIDVALUES DEFINED MDO=... datax returns three variables set as follows:
&X1 = ABCD &X2 = xyz &X3 = QQQ
Example:
If there is a component defined as follows:
datax GraphicString ( FROM ( “A”c | “C” | “Y”C | “X” ) )
then &ASSIGN VARS=X* OPT=VALIDVALUES DEFINED MDO=... datax returns four variables set as follows:
&X1 = A &X2 = C &X3 = Y &X4 = X
When updating the attributes of a list or range of variables:
Specifies the names of the variables to be the target of the assignment operation. If insufficient variables are provided, some data is not available to the procedure. Excess variables are set to a null value. The formats for operands that may be coded with VARS= are:
Supplies leading characters terminated by an asterisk to denote either a numeric or generic range of variables. If the RANGE= operand is specified or allowed to default, then a numeric range is generated. prefix* cannot be used with other variable names.
Specifies the generation of an ascending numeric range by concatenating the supplied prefix with a numeric suffix that is sequentially incremented within the supplied start and end values. The start and end values must be in the range 0 to 32767 and the end value must be equal to or higher than the start value.
Note: If VARS=* is specified, then the range is restricted to 1 to 32767. Specifying a start value of 0 causes an attempt to create an &0 variable. As &0 is a system variable name, this causes the process to fail.
Example:
&ASSIGN VARS=AB* RANGE=(1,3)
creates variable names &AB1, &AB2, and &AB3.
Specifies that the supplied prefix applies to all variables beginning with that prefix. All existing variables in the target range are set to null and target variables starting with the nominated prefix are created by using the FROM variables suffix and data. This option is valid only with OPT=DATA and when both source and target variables are specified as VARS=prefix*.
The MDO operand is also valid.
Note: For more information about using the MDO operand, see the Network Control Language Programming Guide.
Specify that all target variables starting with this prefix, and whose suffix matches the FROM variable suffix, are updated with the contents of the matching FROM variable. This option is valid only with OPT=DATA and when both source and target variables are specified as VARS=prefix*. No variables are created using this option-they can only be updated.
Specifies that target variables starting with this prefix are created with the FROM variable suffix and data, if such a named variable does not already exist. This option is valid only with OPT=DATA and when both source and target variables are specified as VARS=prefix*.
Specifies that target variables starting with this prefix are updated and/or created using the FROM variables suffix and data. This option is valid only with OPT=DATA and when both source and target variables are specified as VARS=prefix*.
Defines a variable, without the ampersand (&). A variable list is specified by enclosing in brackets multiple names separated by commas, for example:
VARS=(VAR1,P$USER,P$TERM)
Denotes the assignment operation modifying or creating variables of the form &1 to &n, depending on how many are needed to satisfy the operation. The RANGE= operand is coded to designate a start number and an end number to delimit the number of variables generated.
Specifies the generation of an ascending numeric range by concatenating the supplied prefix with a numeric suffix that is sequentially incremented within the supplied start and end values. Start and end values must be in the range 1 to 32767, and the end value must be equal to or higher than the start value. For example, the variable names for RANGE=(1,3) are prefix1, prefix2, prefix3.
(For OPT=DATA) Specifies a data constant to be assigned to all target variables. The default is a null value if no FROM or DATA operands are specified.
Indicate that source variables are used as the source of assignment data (OPT=DATA), or to restrict the search for panel-modified variables (OPT=MODFLD). ARGS, VARS=, or MDO= must be coded after FROM.
If the DEFINED_IN keyword is specified, then the information is returned for all those components defined within the connected map, regardless of their presence or absence in the MDO itself.
If the PRESENT_IN keyword is specified, then the information is returned only for those components that are present within the MDO.
If the MANDATORY keyword is specified, then only those defined components that are mandatory are selected.
Specifies a variable list or range, as described previously.
Is a range modifier used to select a non-numeric range of currently existing variables as the source. This operand is mutually exclusive if GENERIC, REPLACE, ADD, and UPDATE are used as target variable specifications. For OPT=MODFLD, GENERIC specifies a non-numeric range of variables to be scanned as MODFLDs. If used with OPT=DATA, source variables are sorted in name order on a character basis.
Denotes that the source variables have the form &1 to &n. The RANGE= operand is coded to designate a start number and end number to delimit the number of variables to be used.
Specifies the entire data section of an MDO as the source or target of the assignment. The value aaa is from 1 to 12 characters long, and is ended with a period (a period is assumed if it is omitted).
Identifies the map that is to be attached to this MDO during the assignment operation.
Specifies an MDO with 1 to 30 component name segments, each separated by a period.
Note: For more information about using the MDO operand, see the Network Control Language Programming Guide.
An index is specified in brackets following any but the first name segment (for example, aaa.bbb{3}.ccc{5}). The index is used to indicate a component within an MDO structure as the source or target of an assignment. See later in this section, for more information on assignment to and from MDOs.
Examples: & ASSIGN
&ASSIGN VARS=(NAME1,USER,PHONE) DATA= -* clear user details &ASSIGN ARGS -* clear &1 - &64 &ASSIGN VARS=S* RANGE=(1,&MAXROWS) -* clear panel selection &ASSIGN VARS=(&ERRLST) OPT=SETERR -* flag fields in error -* &ERRLST contains a name list 'n1,n2,n3' of fields in error.
ASSIGN VARS=D* RANGE=(1,&MAXROWS) + -* set display lines
FROM VARS=DATALINES* +
RANGE=(&TOP,&BOT)
&ASSIGN VARS=SELECT OPT=MODFLD NONULLS +
FROM VARS=S* -* pick up next selection
-* and ignore blanked out
-* selections
&ASSIGN ARGS OPT=MODFLD -* pick up all modified fields
&ASSIGN VARS=SAVE* GENERIC + -* create backup copy variables
FROM VARS=FILEA* -* from file record
-* where &A1 = XXX, &AB = YYY, &DD2 = ZZZ, &DDB = $$$
&ASSIGN VARS=A* BYNAME FROM VARS=DD* -* &AB = &DDB
&ASSIGN VARS=A* OVERLAY FROM VARS=DD* -* &AB = &DDB
-* &A2 = &DD2
&ASSIGN VARS=A* MERGE FROM VARS=DD* -* &A2 = &DD2
&ASSIGN VARS=A* FROM VARS=DD* GENERIC -* &A1 = &DDB
-* &A2 = &DD2
Valid forms of MDO component reference:
MDO=CNM.ALERT.
MDO=CNM.ALERT.PSID{2}.PRODUCT
MDO=PANEL.LINE{15}
MDO=CNM.ALERT.TYPE
MDO=CNM.ALERT.PSID{2}.PRODUCT.SWNAME
MDO=PANEL.LINE{15}.RESOURCE{1}
MDO=PPO.TEXT
Notes:
In all functions, the system variable &ZVARCNT is set to indicate the number of target variables updated.
Using OPT=DATA assignment with overlapping ranges gives results as if all assignments are performed in parallel. This lets you shift data values up and down variable ranges. For example:
&ASSIGN VARS=A* RANGE=(2,5) FROM VARS=A* RANGE=(1,4)
gives the same results as:
&A5=&A4, &A4=&A3, &A3=&A2, &A2=&A1
Setting and resetting ERRFLD and MODIFIED attributes is independent of any MODFLD attribute for a variable. It is therefore possible to flag variables without affecting the MODFLD processing that an NCL procedure may have.
A variable flagged as ERRFLD or MODIFIED is not returned by a MODFLD function until it has been displayed on a panel. A variable retains the MODFLD attribute when a panel is redisplayed until it is reset by &ZMODFLD, by &ASSIGN OPT=MODFLD, or by a panel display that does not contain the variable. Null variables is flagged as ERRFLD or MODIFIED.
If a panel field is overtyped or erased so that the variable contents are unaltered, then it is not returned by the MODFLD function. Also, &CONTROL FLDCTL must be in effect during a panel display for the MODFLD attribute to be updated by panel services.
| Copyright © 2009 CA. All rights reserved. |
|