Add List Multiple Entries (QUIADDLM) API

The Add List Multiple Entries (QUIADDLM) API adds one or more new entries to a list. The new entries are inserted immediately before or immediately after the entry identified by the current entry for the list. They can also be inserted at the beginning or end of the list. On return to the application program, the current entry points to the most recently inserted entry.

The contents of all dialog variables corresponding to columns in the list are saved in each added entry. When the operation completes successfully, the corresponding dialog variables contain the values from the last list entry successfully added.

Authorities and Locks

None.

Required Parameter Group

Application handle

INPUT; CHAR(8)

The application handle assigned by the UIM and returned to the application program by the Open Display Application (QUIOPNDA) API or the Open Print Application (QUIOPNPA) API when the application is opened.

Variable buffer

INPUT; CHAR(*)

The program buffer from which dialog variable values are copied. The dialog variables are copied in the order specified in the variable record definition.

If the variable record name parameter specifies the name of a variable record defined in the panel group for an open application, dialog variables are copied from the variable buffer to the application variable pool before the list entry is added. This parameter operation is the same as using the Put Dialog Variable (QUIPUTV) API immediately before the Add List Multiple Entry (QUIADDLM) API.

The variable buffer must be large enough to contain all the variables specified in the variable record definition.

When the number of records parameter has a value greater than one and the record numbers parameter has a value of zero, the size of the variable buffer must be at least equal to the value on the number of records parameter multiplied by the value on the record size parameter.

When the number of records parameter has a value greater than one and the record numbers parameter has a nonzero value, the size of the variable buffer must be at least equal to the largest value in the array of record numbers multiplied by the value of the record size parameter.

Variable buffer length

INPUT; BINARY(4)

The length of the variable buffer. The buffer must be large enough to contain all the dialog variables in the variable record definition specified in the variable record name parameter.

Variable record name

INPUT; CHAR(10)

The name of the variable record determining which dialog variables are copied from the variable buffer to the application variable pool. The variable record must be defined in the panel group for the open application.

The following special value can be used:

*NONE

The QUIPUTV API is not used during the QUIADDLM API. The variable buffer, variable buffer length, number of records, record size, and record numbers parameters are ignored.

List name

INPUT; CHAR(10)

The name of the list to which entries are added. If the list is not currently active in the open application, it is activated by this API.

Option

INPUT; CHAR(4)

The location of the new entry in the list. When an entry is added to the list, the current entry is always changed to point to the new list entry.

One of the following values must be specified to indicate the new entry's location:

FRST	Added as the first entry in the list
LAST	Added as the last entry in the list
NEXT	Added after the current entry
PREV	Added before the current entry

List entry handle

OUTPUT; CHAR(4)

The list entry handle returned to the application program from the current entry. This value is the handle of the entry just inserted into the list. If more than one list entry is added, this parameter contains the list entry handle of the last entry successfully added.

Number of records

INPUT; BINARY(4)

The total number of entries the application program wants to add to the list. If the variable record name parameter specifies the name of a variable record defined in the panel group for this open application, this parameter can be used with the record size, record count, and record numbers parameters to add multiple entries to the list. When the variable record name parameter has the value *NONE, the number of records parameter is ignored.

The following special value can be used:

1	Only one entry is added to the list. The record size, record count, and record numbers parameters are ignored.

When the number of records parameter is greater than 1, the variable buffer parameter must contain all the entries to be added to the list. The record size parameter defines the size of each record within the variable buffer, and is used to calculate the offset of each record from the first record. The variable record, identified by the variable record name parameter, defines the format of each record.

Record numbers

INPUT; CHAR (*)

An array of record numbers. Each entry in the array is a BINARY(4) value from 1 to 32767. The array specifies the order in which entries are added to the list. The first record number defines the first entry added to the list, the second record number defines the second entry, and so forth. Each record number specifies a record from the variable buffer containing the values for an entry to be added to the list. The dimension of the array must be at least as large as the value for the number of records parameter.

The following special value can be used in the first array element:

0	Records from the variable buffer are used in sequential order. The array of record numbers needs to have only one element.

When the record numbers parameter is 0, the size of the variable buffer must be at least equal to the value specified on the number of records parameter multiplied by the value on the record size parameter. When the record numbers parameter has a nonzero value, the size of the variable buffer must be at least equal to the largest value specified in the record numbers array multiplied by the record size value.

The record numbers parameter allows applications to add more than one list entry from data structures already available to the application program. This is useful when the existing order of records in the data structures is not desired for the list entries, or when certain records should not be added to the list.

Record size

INPUT; BINARY(4)

The size of each record within the variable buffer when multiple records are added to the list. The record size is also used to calculate the offset of each record after the first record.

When the number of records parameter is 1, this parameter is ignored.

Record count

OUTPUT; BINARY(4)

The number of list entries actually added. Validation is done on packed or zoned data values in each record. If an error is found, the Add List Multiple Entries (QUIADDLM) API ends at that point with an exception; unusable data causes a partial update of the list. This parameter returns the number of list entries successfully added to the application program, even if an error occurs.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Error Messages