ITEM= Statement

Defines the fields within the record.

Type:	Required statement
Applies to:	access descriptor

Syntax

Required Arguments

Optional Arguments

Details

Syntax

ITEM= item-name LEVEL=level-number

DBFORMAT=database-format <SASNAME=SAS-name>
<FORMAT=SAS-format > <SEARCH=search-name>
<KEY=Y | N | U> <OCCURS=number-of-repeats>
<DBCONTENT=database-content> ;

Required Arguments

In the ITEM= statement, you must enter the item name, level number, and the DBFORMAT= argument.

LEVEL= | LV=

specifies the two-character numeric level of the IMS field. This level number is similar to the COBOL level number. To indicate that a field is in a group, the field's level number must be greater than the group's level number. This is a required argument.

DBFORMAT= | DBF=

specifies how the IMS field is stored in the database. This table also shows the SAS variable formats that the SAS/ACCESS interface to IMS generates for the DB Formats.

You must specify one of the following SAS informats in this argument. For character data, the SAS informats are as follows:

Character Informats for DBFORMAT=
$w.	$HEXw.
$CHARw.	$PHEXw.
$CHARZBw.

For numeric data, the SAS informats are as follows:

Numeric Informats for DBFORMAT=
w.d	ZDBw.d	RBw.d
Fw.d	IBw.d	PDw.d
BZw.d	PIBw.d	PKw.d
ZDw.d	HEXw.

Optional Arguments

The other arguments define the item further and are not required.

SASNAME= | SN=

is supported for SAS 6 compatibility only. It assigns a SAS variable name to the IMS field. When VALIDVARNAME=V6, the name assigned to this argument is also used as input to the subsetting WHERE statement.

FORMAT= | FMT=

assigns a SAS format to the SAS variable. This is an optional argument.

If you specified the AN= statement with a value of Y, SAS assigns default formats (based on the field's database format) to the variables when the access descriptor is created. If you want, you can enter formats using the FORMAT= argument in the ITEM= statement at that time. However, you are not able to change these formats when you create a view descriptor from this access descriptor after the access descriptor is created.

SEARCH= | SE=

specifies the search field name defined for the field in the DBMS DBD. If you want the IMS engine to create SSAs directly from a WHERE statement or command that references the named item, then you must assign search field names. Otherwise, the WHERE statement is passed to SAS, and all occurrences of the segments referenced in the view descriptor in the database are read and passed to SAS for further processing. See Performance and Efficient View Descriptors for more information about SSAs and WHERE statements. This is an optional argument.

KEY= | K=

indicates with a Y, N, or U whether this field is defined in the DBD as a sequence or key field and whether the key sequence field is unique. The default setting, N, indicates the field is not a key sequence field. You must assign one key sequence field per segment if you use the view descriptors created from this access descriptor to update the IMS database. Keys are recommended, but not required, for all segments except the lowest hierarchical level if the view descriptors are used only for data retrieval. When KEY=U, retrieval calls to IMS are reduced because the IMS engine knows that there is only one segment in the database for this key.

OCCURS= | O=

indicates the number of times a repeating field occurs. This is an optional argument.

DBCONTENT= | DBC=

indicates that the values for this field need special handling by the IMS engine. This is an optional argument. You can use this argument to specify a SAS format that indicates the way date values are represented internally in the IMS database, or to indicate how a field is initialized or stored in the database. This is not the same as the value that you entered in the DBFORMAT= argument.

For example, you would use the DBFORMAT= argument to specify that a date is stored as a packed decimal. You would then use the DBCONTENT= argument to indicate where the month, day, and year are stored in that packed decimal. The following are valid parameters for date values:

Valid Parameters for Date Values
YYMMDD6.	DDMMYY6.	JULIAN5.
YYMMDD8.	DDMMYY8.	JULIAN7.
MMDDYY6.	TFGY2KD4.*
MMDDYY8.	TFGY2KN4.*

* The TFGY2KD4. and TFGY2KN4. values indicate a 4-byte packed decimal value that is stored in the IMS database in the form 'CYYMMDDS'x, where C=century (0=1900, 1=2000), YY=year, MM=month, DD=day, and S=sign (C). TFGY2KD4. interprets the packed decimal value and converts it to a SAS date value, which is represented as the number of days since January 1, 1960. For example, '0990101C'x is interpreted as January 01, 1999, and is converted to the value 14245. You can then use the FORMAT= statement to apply a SAS format to the value. TFGY2KN4. interprets the packed decimal value as an 8-byte number and converts it to a numeric value. For example, '1990101C'x is interpreted as January 01, 2099, and is stored as 20990101. When the database is updated, the SAS values are converted back to the packed decimal format. When TFGY2KD4. or TFGY2KN4. are entered for DBC=, a DBFORMAT= of PD4. or PD4.0. must also be specified or SAS issues an error message.

The following are valid parameters for special formats values that indicate how a field is initialized:

B	when values are blanks for zero.
H	for high values.
L	for low values.

These special formats affect how SAS displays and updates the fields in the database. Use special format B to indicate to the IMS engine that a numeric variable has blanks when its value is zero. Use the special codes H and L to indicate that a variable is initialized to high or low values, respectively. For example, if you specify L for a variable, SAS displays a missing value when it finds low values (hexadecimal zeros) in the variable. If you update that variable with a missing value, the IMS engine writes low values to the variable in the database. If you specify H for a variable, SAS displays a missing value when it finds high values (hexadecimal Fs) in the variable. If you update that variable with a missing value, the IMS engine writes high values to the variable in the database.

You can also use the special formats values when a date is initialized in a special way. For example, if you have a date initialized to low values, enter, enclosed in single quotation marks, the date format followed by a slash (/) and an initialization code. For example, for an eight-digit date in the MMDDYY8. form initialized to low values, you would enter the following value for the DBCONTENT argument:

'MMDDYY8./L'

Do not specify a DBCONTENT for records and groups.

Details

The ITEM= statement defines the fields within the record. The item name is the name that you assign to the field in an IMS database segment and which SAS/ACCESS software uses to generate a SAS variable name. This name can be a maximum of 32 characters. If any special characters or blanks are included in the name, enclose the entire name in single quotation marks. This is a required argument.

The generated SAS variable name uses the naming conventions specified by the VALIDVARNAME system option. For information about VALIDVARNAME, see the SAS System Options: Reference.

If you specified the AN= statement with a value of Y, you cannot change the SAS variable names when you create a view descriptor from this access descriptor after the access descriptor is created.

If you specified the UN= statement with a value of Y, the variable names are unique. Any duplicate names are resolved as follows: the name is truncated to the legal length and a number appended to the end to identify it as unique. For example, two instances of CUSTOMER_ADDRESS would be changed to CUSTOMER_ADDRESS and CUSTOMER_ADDRESS0.

Sites commonly refer to undesired portions of the data buffer by using the FILLER notation in the ITEM= statement and by defining the DBC (DB Content) as $CHAR.