CFDE - Create Field Definition Entry Macro

Defines an external field name and internal characteristics and attributes for a field contained in a structured CA ACF2 record.
acf2src
Defines an external field name and its related internal characteristics and attributes for a field to be contained in a structured CA ACF2 record, such as a logonid record or an RSB module. When the ACFFDR is reloaded, changes to the @CFDE macro take effect immediately. CA reserves certain @CFDE operands for its own use.
The AUTH, ALTER, and LIST authorization operands assume basic access to the record is involved. Privileges such as SECURITY and ACCOUNT defined in the requester’s logonid record and associated SCPLIST value, determine a user’s access to the record itself. CA ACF2 verifies access to the record prior to and independently of field-level access controls. Once CA ACF2 grants access to the record, individual field authorizations (AUTH, ALTER, and LIST) are verified. Record access privileges supersede any field-level controls.
Syntax
@CFDE name,symbol,type,AUTH=fieldname,ALTER=0|list, LIST=0|list,FLAGS=0|list,BITMAP=0|bitmap, PRTN=0|nn,RRTN=0|nn,GROUP=0|nn, MVFLAGS=0|list,MVHDR=0|STD|NONE, MVMIN=0|min,MVMAX=1|max, VRTN1=0|num|pgmname, VRTN2=0|num|pgmname,VPRM1=0|addr, VPRM2=0|addr,DFTAD=0|addr,DFT=, ZERO=NO|YES,PROMPT=NO|YES,TRIM=YES|NO, VER=0|nnn,CBPROC=NO|YES,COUNTER=NO|YES
Operands
  • name
    Specifies the external field name. For logonid records, all of the eTrust CAACF2-supplied fields are described in
    Logonid Records
    . The operand name specifies the external name for a field (the name by which the ACF command refers to it). It is one- to eight-characters long and contains any characters that are valid in an assembler character constant. If name contains any special characters, enclose it in apostrophes. If name contains apostrophes or ampersands, you must double these characters, as in standard assembler character constant practice.
  • symbol
    For logonids, specifies the symbolic label or internal field name assigned to the logonid field in the LIDREC DSECT. For RSBs, symbol specifies the label on the field in the mapping DSECT that describes the structured infostorage record.
  • type
    Specifies the field type. Valid field types are:
    • BINARY
      Determines the maximum value that can be assigned to the field. Binary fields can be defined as being one to four bytes long. Only binary two and four-byte fields can contain negative values. The permissible formats are as follows: A one- to four-byte binary field.
      • ddddd
        Specifies up to five binary digits with no sign assigns the specified value to the field.
      • +ddddd
        Specifies the string that is preceded by a plus sign increments the field value by the specified value.
      • ddddd-
        Specifies the minus sign decrements the field value by the specified value.
    • BIT
      Indicate bits that are turned on through specification of the field name. For example, TSO grants the TSO attribute. Specification of the field name that is preceded by the keyword NO turns off the bit. NOTSO turns off the TSO attribute. On output, the field is listed only as the field name or the field name that is preceded by the word NO. Optionally, the listing of the field can be suppressed if the bit is off. A bit field used as a switch or flag.
    • CHAR
      Specifies a text field of 1 to 255 bytes. Specified with the field name followed by the value of the field in parentheses. To specify a blank field, the null string of () can be used. Optionally, the listing of the field can be suppressed if the field is blank or zero. A text field of 1 to 255 bytes.
    • CHEN
      Specifies a four-byte encoded character field (password). For RSBs,
    • CHEN
      Specifies an encrypted character field up to 255 bytes long.
    • HEX
      Specifies a string of valid hexadecimal digits (09, AF) of even length, which is enclosed in parentheses. Hexadecimal fields can be defined as a maximum of eight bytes (16 hexadecimal digits). The assignment to the field is left-justified. Trailing zeros are truncated. Optionally, you can suppress the listing of the field if the value is zero. 1- to 255-byte hexadecimal field.
    • PACKED
      Specifies the field name followed by the Gregorian date in parentheses. The format that is specified in the DATE field of the GSO OPTS record determines how to enter dates (mm/dd/yy, dd/mm/yy, yy/mm/dd). For more information, see Maintaining Global System Options Records. Optionally, the listing of the field can be suppressed if the value is zero. A four-byte packed decimal date field.
    • TIMEBIN
      Specifies a four-byte binary format time whose value is expressed in units of 0.01 seconds past midnight.
    • TOD
      Specifies an eight-byte time stamp in number of microseconds past January 1, 1900 (store clock instruction).
  • AUTH=
    fieldname
    Specifies the external name of a bit field that must be set in a user’s logonid record to enable him to alter this field. The external field name refers to a CA ACF2-supplied bit field or a user-defined bit field name. AUTH validation checking is performed after ALTER validation checking.
  • ALTER=
    0
    |
    list
    or LIST=0|
    list
    Identifies privileges that can modify (ALTER) or display (LIST) this field. Select multiple entries using a plus sign (+); however, do not use a plus sign with ALL. For example, you should not enter ALTER=ALL+USER because unpredictable results can occur. However, ALTER=SECURITY+ACCOUNT indicates that any user having the SECURITY or ACCOUNT privilege can alter this field. A minus sign (–) limits the ALTER or LIST operands. With this delimiter, enter ALL as the first entry or the only entry. Separate subsequent entries with minus signs. For example, LIST=ALL-USER indicates that all requesters can list the field except for those having only the USER privilege.
    Use caution when specifying ALTER=ALL. CA ACF2 does not allow users with only the AUDIT privilege to change fields in other users’ logonid records. However, if you specify ALTER=ALL, users can change fields in other users’ logonid records. In most cases, you will want to specify ALTER=ALL-AUDIT instead of ALTER=ALL. This configuration still allows AUDIT users to change fields in their own logonid records but they are not able to change fields in other users’ logonid records. The ALTER and LIST defaults are 0 (no accesses are allowed). The following are the privileges that you can specify:
    • SECURITY—Security administrator
    • ACCOUNT—Account manager
    • AUDIT—Auditor
    • LEADER—Project leader
    • USER—Normal user
    • CONSULT—Consultant
    • ALL—All of the above
  • FLAGS=
    0
    |list
    Provides a set of special field handling options that are described in the following. Join multiple options with a plus sign (+). The options are:
    • HUNDRED—For binary fields, the internal form is .01 units, while the external form is in units (ones).
    • LIMIT—Do not return this field to requesters suppressing trivial fields. The SET NOTRIVIA subcommand of the ACF command supports LIMIT. This flag indicates that the field is displayed only when the entire record (that is, all fields in the infostorage or logonid record) is requested.
    • MULTIVAL—This field supports multiple values.
    • MUTEXC—All bits in the byte are mutually exclusive and all bits in the byte are zeroed before any are turned on. This option is for bit fields only.
    • NEVER—Never return this field in response to a formatted retrieval request. For example, CA ACF2 will not display this field when the LIST subcommand is issued.
    • NULL—If the field value is unspecified, do not display the field name or value.
    • RESTRICT—Only unrestricted security administrators can change this field. This means users with the SECURITY privilege and no SCPLIST restrictions specified in their logonid records.
    • SPECIAL—With this field, the ACF command bypasses validity checking of an input field value. The ACF command normally checks the length of character information and the maximum size of binary information. Use this option when the field value is a keyword or a string that is transformed by the processing routines contained in the eTrust CAACF2 SVC.
  • STATUS=
    0
    |list
    • Provides a set of special field status options that are described below. Join multiple options with a plus sign (+).
    • DATALONG—For CA ACF2 internal use only
    • LOWERCSE—Supports lower case values
    • NULLOK—For CA ACF2 internal use only
    • PSEUDO—For CA ACF2 internal use only
    • SNGLQT—Supports Single Quotes in user defined fields for LIDs only.
    : It is highly recommended that LID fields with the SNGLQT attribute not be defined in the UID string. It is recommended that the SNGLQT attribute not be used with any multi-valued field
  • BITMAP=
    0
    |bitmap
    Indicates the bit pattern that represents the “on” condition for a bit field. This operand is an equated value with a single bit set (for example, X’20’). The “on” condition must be represented by a one bit; you cannot have a flag that is on when its bit is off.
    BITMAP applies only to fields with a type of BIT. BITMAP indicates the bit configuration that represents the particular bit flag in a byte. For example, suppose a byte contains two bit flags, defined like this in the mapping DSECT for the structured infostorage record:
    FLAGBYTE DS X A BYTE OF BIT FLAGS BITFLAG1 EQU X’80’ ...THE FIRST BIT FLAG BITFLAG2 EQU X’40’ ...THE SECOND BIT FLAG
    The @CFDE macros for these two flags looks like this:
    @CFDE FLAG1,FLAGBYTE,BIT,BITMAP=BITFLAG1,... @CFDE FLAG2,FLAGBYTE,BIT,BITMAP=BITFLAG2,...
  • PRTN=
    0
    |
    nn
    Indicates the processing subroutine ID. CA ACF2 uses this subroutine to convert the input data entered using the CHANGE or INSERT subcommands to the proper format for storage in the CA ACF2 database. You do not have to specify a processing subroutine ID for standard CA ACF2 data types. See the RRTN operand for a list of CA ACF2-supplied processing subroutines.
  • RRTN=
    0
    |
    nn
    Identifies the reconstruction subroutine ID. CA ACF2 uses this subroutine to convert data stored in the CA ACF2 database into display format for the LIST subcommand output. You do not have to specify a reconstruction subroutine ID for standard CA ACF2 data types.
    The CA-ACF2-supplied processing and reconstruction subroutines are listed in the following:
    SUBRTN-ID
    Process (PRTN)
    Reconstruct (RRTN)
    Notes
    0
    NULL
    NULL
    1
    1
    CHARACTER
    CHARACTER
    NA
    2
    PACKED
    PACKED
    2
    3
    SWITCH
    SWITCH
    NA
    4
    BINARY
    BINARY
    3
    5
    PASSWORD
    TOD
    NA
    6
    CANCEL/SUSPEND
    CONSTRUCT UID
    NA
    7
    LINE/ATTN
    LINE/ATTN
    NA
    9
    CHAR
    NA
    NA
    10
    CHAR(MASK)
    CHAR(MASK)
    4
    11
    HEXADECIMAL
    HEXADECIMAL
    5
    12
    DATA ENCRYPTION
    NA
    6
    13
    PREVENT/LOG/ALLOW
    PREVENT/LOG/ALLOW
    7
    16
    MULTIVALUE BIT-SET
    MULTIVALUE BIT-SET
    8
    • Note 1: If PRTN= (no processing subroutine) or RRTN= (no reconstruction subroutine) is specified, CA ACF2 determines the appropriate subroutine from the TYPE operand. If a subroutine ID of zero is specified (PRTN=0 or RRTN=0), the ACF command cannot alter or display this field.
    • Note 2: This subroutine assumes all packed fields are dBinary values contain commas when displayed.
    • Note 3: Binary values contain commas when displayed.
    • Note 4: These subroutines assign the specified string to the designated field. They also expand a trailing dash to all asterisks and, upon reconstruction, reverse the process.
    • Note 5: This subroutine assigns the hexadecimal value to the designated field.
    • Note 6: This processing subroutine uses the CA ACF2 data encryption routine ACF00ENC. This subroutine is an XDES, two-step, irreversible encryption subroutine. The eight-byte key used to create the cipher is the external @CFDE name used for the FDE. (See
      Interface with CA ACF2
      for more information about ACF00ENC.)
    • Note 7: These subroutines process fields with acceptable values of PREVENT LOG, and ALLOW. These values are stored internally as P, L, and A.
    • Note 8: These subroutines process and reconstruct multiple values of bit-set fields. See Creating Structured Infostorage Records in
      Special Usage Considerations
      for more information about defining multivalue bit-set fields.
      The CA ACF2 system configuration supports processing and reconstruction subroutines with IDs from 1 to 20. If you add your own subroutines, use the IDs 17 through 20 (starting with 20 and moving backwards) to avoid conflicts with future CA ACF2 development.
  • GROUP=
    0
    |
    nn
    Identifies the display group where the output is to be formatted. See @GROUP - Group Name for Record Formatting for information about how to add or modify groups and group names. The CA ACF2-defined group names are listed in the following:
    • 0—Identification Section (header)
    • 1—CANCEL/SUSPEND
    • 2—PRIVILEGES
    • 3—ACCESS
    • 4—PASSWORD
    • 5—TSO
    • 6—STATISTICS
    • 7—CICS
    • 8—IMS
    • 9—IDMS (Note: this group is no longer used)
    • 10—MUSASS
    • 11—RESTRICTIONS
    • 12—DFP
  • MVFLAGS=
    0
    |
    list
    Provides support for multivalue fields. Join multiple options with a plus sign (+). For example, MVFLAGS=ALLOWDUP+REPONLY indicates that you can specify duplicates in this field and replace a value but cannot add or delete one. Here are the options you can specify:
    • ALLOWDUP—Indicates that duplicate values are allowed in a multivalue field.
    • DYNAMTL—Indicates that the multivalue field has a dynamic variable total length. This is required for multivalue bit-set fields.
    • REPONLY—Specifies that this multivalue field must be entirely replaced. You cannot add or delete values in the list. For example, the MODE field of the GSO OPTS record lets you specify RULE as one of its values. However, you must also specify a no-rule and a no-$mode parameter with RULE, so that the MODE field looks like RULE,LOG,QUIET. With the REPONLY option, the field is designated as replace only.
  • MVMIN=
    0
    |
    min
    Specifies the minimum number of values the field can hold for a multivalue field.
  • MVMAX=
    1
    |
    max
    Specifies the maximum number of values the field can hold for a multivalue field. This value is usually the same as the value specified for MAX on the AMULTFLD macro for the field. For multivalue bit-set fields, specify 1 for this field.
  • MVHDR=
    0
    |STD|NONE
    Identifies whether CA ACF2 uses field header information as defined by the AMULTFLD macro. The AMULTFLD macro defines the amount of storage required by multivalue fields. Multivalue bit set fields do not require field header Information. Therefore, the AMULTFLD macro is not used with these fields. This field indicates whether CA ACF2 uses the AMULTFLD macro.
    • STD—Specifies that standard field headers are used. See the AMULTFLD macro for information about multivalue field headers.
    • NONE—Specifies that a field header is not required for multivalue bit-set fields.
  • VRTN1=
    0
    |num|pgmname
    Identifies the CA ACF2 validation subroutine that verifies that the data entered in a field is appropriate for that field. Validation subroutines obtain control before the processing subroutine described previously. If pgmname is specified, you must link edit the associated program (CSECT) into the RSB load module. If num is specified, you must link edit the associated CSECT into the ACF00VSR module. This operand is optional and does not have to be specified for user-defined fields. A VRTN1 subroutine cannot perform I/O to the Infostorage database using the ACFSVC macro. The VRTN1 validation subroutines supplied with CA ACF2 include:
    • 0
      —No additional validation is required. This value is the default.
    • 1
      This subroutine validates the source for a character-field replacement. The source field must be a valid program or data set index-level name that is one- to eight-characters in length. The first character cannot be numeric; the remaining characters can be alphanumeric or national. A blank string is considered valid.
    • 2
      This subroutine validates a source character field. It checks for a valid z/OS data set name. Generation data group (GDG) relative version numbers and partitioned data set (PDS) member names are not supported.
    • 3
      This subroutine matches a character value to a list value. This list is defined in the @VALUES macro referenced by the VPRM1 operand in the @CFDE macro.
    • 4
      This subroutine validates a binary value range. This range is defined in the @VALUES macro referenced by the VPRM1 operand in the @CFDE macro.
    • 5
      This subroutine checks that a logonid record password update requested by the user is not performed until the MINDAYS interval contained in the logonid record has expired.
    • 16
      This subroutine checks that a value entered for a bit-set field is an acceptable value for the set. The set is defined in the @VALUES macro referenced by the VPRM1 operand in the @CFDE macro. When the subroutine checks the first value, it initializes the work area and determines if the set of values in @VALUES is a discrete value list or a sequential range of numeric values. Fields initialized in the work area preserve this information for subsequent calls for the same multivalue field so that the PRTN subroutine 16 can process the value to set or reset the bit without revalidating the value string.
  • VRTN2=
    0
    |num|pgmname
    Identifies a CA ACF2 validation subroutine that verifies the entire list of values for a multivalue field or identifies a second validation subroutine. If pgmname is specified, you must link edit the associated program (CSECT) into the RSB load module. If num is specified, you must link edit the associated CSECT into the ACF00VSR module. This operand is optional. A VRTN2 subroutine cannot perform I/O to the Infostorage database using the ACFSVC macro. VRTN2 validation subroutines supplied with CA ACF2 include:
    • 0—This subroutine specifies that no additional multivalue field validation is required. This value is the default.
    • 1—This subroutine sorts the values of a multivalue field so that they can be easily recognized when displayed.
    • 14—This subroutine verifies that the value given for a two-byte or a four-byte binary field is not negative.
    • 16—This subroutine validates the values of a multivalue bit-set field after the alter request entries (AREs) have been processed to update the field. The AMULTFLD macro is reset with the proper header information so that the field is properly copied back into the record.
  • VPRM1=
    0
    |addr
    Specifies a parameter that is passed to the VRTN1 field validation subroutine. The only CA ACF2 distributed validation 1 (VRTN1) subroutines that use this parameter are 3, 4, and 16. This parameter points to a value list generated by the @VALUES macro. Use the label of the @VALUES macro as the addr for this operand.
  • VPRM2=
    0
    |addr
    Specifies a parameter that is passed to the VRTN2 field validation subroutine. No CA ACF2 distributed validation 2 (VRTN2) subroutines currently use the VPRM2 operand. This parameter points to a value list generated by the @VALUES macro. Use the label of the @VALUES macro as the addr for this operand.
  • DFTAD=
    0
    |addr
    Specifies the address of the @CFDEDFT macro, which provides a default value for the field defined by this @CFDE macro. For addr, specify the label used in the @CFDEDFT macro. This field cannot be used with the DFT operand; they are mutually exclusive.
  • DFT=
    Specifies the default value for the field when the record is inserted with the INSERT subcommand. If neither the DFT nor DFTAD operand is specified, the default for each type of field is as follows:
    • BINARY—0000
    • BIT—RESET (use DFT=SET to turn on the switch)
    • CHAR—Blanks
    • CHEN—Blanks
    • HEX—X‘00’
    • PACKED—00000000
    • TIMEBIN—0000
    • TOD—00000000
    This field cannot be used with the DFTAD operand; they are mutually exclusive.
  • ZERO=
    NO
    |YES
    Indicates whether the corresponding record field in the model is copied when using the INSERT USING subcommand. For the default of ZERO=NO, the record field is copied from the model. ZERO=YES prevents the field from being copied from the model.
  • PROMPT=
    NO
    |YES
    Indicates, when a value is omitted from this field, whether the user is prompted to enter a value in a nondisplay protected area. This operand is useful for fields where sensitive information, such as a password, is added or changed. The default is PROMPT=NO.
  • TRIM=
    YES
    |NO
    Indicates whether trailing blanks are removed from character fields or zeros removed from hex fields when the fields are displayed. The default of TRIM=YES removes trailing blanks or zeros.
  • VER=
    0
    |
    nnn
    Provides a one-byte binary area to identify the version ID of a field in a structured infostorage record.
  • CBPROC=
    NO
    |YES
    Indicates whether authorized programs can bypass processing routines when updating the field. This operand is used for CA ACF2 internal processing. Do not code a value for it.
  • COUNTER=
    NO
    |YES
    Specifies whether a binary field is a counter. Counter fields are updated by addition or subtraction, rather than replacement. This ensures that counts are not lost when multiple, almost concurrent updates are made. You cannot use the VRTN1 field validation subroutine 3 with counter fields.
Specifications
Required for the supplied CA ACF2 entries; optional for the addition of user fields. You can specify a total of 4096 @CFDE macros in the ACFFDR for logonid record processing or in each record structure block (RSB).
If you add fields to the logonid record, you must also modify the LIDREC DSECT to define the size and location of each additional field. Remember to properly initialize any new character fields on all logonids using the appropriate ACF CHANGE global command. Otherwise, the new field will contain binary zeros, instead of blanks.
Modifications to the ACFFDR source module and LIDREC DSECT should be made using the sample USERMOD UM99901. This USERMOD is found in the CAI.ACF2.CAX1JCL0 data set. The LIDREC DSECT resides in CAI.CAX1MAC0; the ACFFDR resides in CAI.CAISRC.
The length attribute of the symbol in the LIDREC DSECT determines the length of the logonid fields.
When adding fields to the logonid record:
  1. Determine additional or different fields to be used and write the field definition @CFDE macros.
  2. Modify the USERLID section of the LIDREC DSECT to reflect any new @CFDE entries.
  3. IPL with the ACFFDR that contains the new @CFDE entries and modify all logonid records so that the contents of these fields are meaningful for the type of field. You can use the following command for global changes:
    ACF CHANGE LIKE(-)
For an example of @CFDE and @MLID changes including the modification of the logonid record (LIDREC) mapping DSECT and mapping of the logonid record to include the new fields, see the
CICS Interface Preinstallation Considerations - Define Additional CICS System Entry Authorizations.
Defaults
All CA ACF2-defined fields in the logonid record are represented in the LIDREC DSECT. The @CFDE macros for all CA ACF2-defined logonid record fields are found in member ACFCFDE in the CAI.CAX1MAC0 data set. Member USERCFDE in CAI.CAX1MAC0 is for user-defined LIDREC fields. For directions on how to obtain a printed copy of this DSECT, see Parameter Lists and Mapping Macros.
The SHOW FIELDS subcommand of the ACF command displays the external names of the logonid record field as defined by the @CFDE entries. Note that the SHOW FIELDS display all logonid field names that you have the authority to view or modify. If your logonid has any special privileges (SECURITY, ACCOUNT, AUDIT, LEADER, or CONSULT), this display includes the fields you can modify in the logonid records of other users. For more information, see SHOW Subcommand - All Other Settings.