Directives

IOLIST

Specify Variable List

Format

Define List: IOLIST {parm[:[format]...}

Note:
The inner set of brackets enclosing [,format] are part of the syntax.

Where:

parm

Set of parameters to be used in an input/output directive. This includes Variables, Literals, Mnemonics, IOL= options, and/or location functions such as '@(...)'.

format

Defines how the field is formatted. Options include:

CHR(len [, SEP=dlm])

Variable length string (Optional SEP= clause indicates not to extend beyond dlm character.)

When written, trailing spaces will be added or data will be truncated. On reading, trailing spaces will be deleted.

CHR(dlm [, SIZ=len])

Variable length string (Optional SIZ= clause indicates when writing, append spaces or truncate to len characters.)

When written, the character identified by dlm will be appended.

DEC( [SEP,SIZ=] len[,scl])

Fixed length, explicit decimal, sign maintained. Numeric fields are padded with leading spaces. (Optional SEP,SIZ= clause allows for padded numeric fields followed by a field separator.)

LEN(len [, SEP=dlm])

Variable length string (Optional SEP= clause indicates not to extend beyond dlm character.)

When written, trailing spaces will be added or data will be truncated.

LEN(dlm [, SIZ=len])

Variable length string (Optional SIZ= clause indicates when writing, append spaces or truncate to len characters.)

When written, the character identified by dlm will be appended.

STR(dlm)

Quoted string.

STR(+)

(Used for INPUT Only)

Special PxPlus format used with WindX data packets.

If parm is a numeric variable, it receives the length of string but does not advance.
If parm is a string variable, it receives the string value.

BCD(len [,scl])

Packed decimal numeric.

BIN(len [,scl])

Binary numeric.

INT(len [,scl])

Unsigned integer numeric.

NUM(len [,scl])

Fixed length unsigned numeric.

SGN(len [,scl])

Fixed length signed numeric. Sign character is trailing.

Where:

len

Length of the field in the record

 

dlm

String whose first character delimits the field

 

scl

Optional scaling factor to apply to the number (e.g. 2 indicates that 1.34 is output as 134)

 

The following options define data validation (each option is separated by a : colon) - see Data Validation:

(The options DTE, MAX, MIN, PRC and TBL were added in PxPlus 2017.)

DTE(string)

Defines that the variable is a date. Must be in the format as defined by the ODBC DATE-xxx class rules.

For string variables only, null string is acceptable.

MAX(n)

Indicates the maximum length (for string) or the maximum value (for numeric).

MIN(n)

Indicates the minimum length (for string) or the minimum value (for numeric).

PRC(n)

(For Numeric Variables Only) Defines the maximum precision.

TBL(string)

Defines the validation string in accordance with the existing Data Dictionary validation string.

Description

Use IOLIST to define a common I/O parameter list (IOLIST). The system ignores the IOLIST directive when it encounters it during program execution until it is used in conjunction with file I/O directives (e.g. READ, WRITE, etc.) and composite string definitions. See Input and Output Parameters.

Note:
IOLIST must be the only directive in a statement.

Data Validation

If the formatting options DTE(string), MAX(n), MIN(n), PRC(n) and TBL(string) are specified, the system will automatically validate the data when the IOLIST is processed on a WRITE, UPDATE or REC (IOL=) function (i.e. when the IOLIST is used to create a record layout).

To create this extended IOLIST, the system will automatically add these options based on the Data Dictionary definition to the IOLIST generated by an OPEN (,IOL=*) if an OPT="VALIDATE" is specified on the OPEN, or the Data Dictionary header indicates that it is to be checked. See Force Data Validation on WRITE/UPDATE in Data Dictionary Maintenance.

The rules that determine the validation options that will be added are:

DTE(n)

DTE will be included if the data class is DATE-xxx in accordance with ODBC processing.

MAX(n)

For numerics, MAX is calculated as: 10^digits-10^(0-scale).

Example:

     For a variable defined as 6.2: 10^6-10^(0-2)=999999.99

For strings, the field size is used.

MIN(n)

For numerics, if no format mask exists or a -, +, CR or DB is present in the format mask, MIN will be set to the value of the 0-MAX(n) value; otherwise, it is set to 0.

For strings, if the REQUIRED field flag is set, MIN(1) will be defined.

PRC(n)

PRC will be based on the scale for the numeric variable.

TBL(string )

TBL will be present if a data dictionary validation string exists.

Note:
The TBL( ) validation rule supports the use of fixed values or expressions. The expression is evaluated when the file is opened. Should the expression fail to evaluate (syntax error, bad data), the file OPEN will fail.

(Support for the inclusion of expressions in the TBL( ) validation rule was added in PxPlus 2018 Update 1.)

In the event that a validation fails, an error will be generated:

For Numeric Variable Errors:

The system will generate an Error 41: Invalid integer encountered (range error or non-integer).

For String Errors:

The system will generate the following errors:

MAX/MIN

Error 46: Length of string invalid

TBL

Error 71: String not found

DTE

Error 35: Invalid date/time specified

In addition to generating the error, the system will add the following descriptive text to MSG(-1) regarding the specific error:

VARIABLE too long, exceeds nn char

VARIABLE less than min value

VARIABLE cannot be empty

VARIABLE too short, less than nn char

VARIABLE invalid PRC( ) validation

VARIABLE has more than nn decimal places

VARIABLE has invalid date validation, must use DATE-JUL class

VARIABLE length > 4 for DATE-????

VARIABLE class invalid (DATE-JUL????)

VARIABLE length of date should be nn

VARIABLE is an invalid date

VARIABLE value invalid, must be VALIDATION-RULES

(Data Validation support was added in PxPlus 2017.)

Example

IOLIST (Without Validation):

0010 open (20)"CSTFLE"
0020 read (20,key=C$)iol=1000
0030 let J=J+10
0040 write (20,key=C$)iol=1000
0050 write (21)iol=1010
...
1000 iolist C$,C1$,C2$,C3$,J,K,L,M
1010 iolist C$:[chr(10)],C1$:[chr(40)]

IOLIST (With Validation):

iolist CST_KEY$:[max(7):min(7)],CST_NAME$:[max(30):min(1)],CST_OWING:[max(99999999.99):prc(2)],CST_TYPE$:[max(1):tbl("A,B,E-H")],CST_CREATED$:[max(8):dte("YYYYMMDD")]