Parameters

Description

Build Attribute String builds and returns the argument's attribute string, which is used to call an IBM i program. The Argument String sends the Input/Output information, and the type, and length of the argument. Use this method to build a string in the correct format. For more information on how to use this method, click here.

Argument Type

Select the argument's data type from the drop-down list. You can select:

• Alpha

• Numeric

• Zoned

Argument Length

Enter the length of the argument. This must be a numeric value. It refers to the number of integer digits. This field lets you select the number of digits that will appear to the left of the decimal point.

Argument Direction

Select whether the argument is an input or an output. You choose this from the drop-down list.

Structure Begin/End

Select where the argument is in the structure. You can choose Begin or End from the drop-down list.

Argument Attribute String

Click to open the Variables List. Select a variable where the Attribute string is returned. You can use this parameter in the Program Call method's Argument Attribute String parameter. To build an Argument Attribute String to call an IBM i program that has, for example, three parameters, you call this method three times and assign a flow variable to the last parameter in all three methods.

Clear Queue method clears all data from the indicated Data Queue, or clears specific messages if they are identified by the key specification from a keyed Data Queue.

Data Queue Name

Enter the name of the data queue from where you are clearing the data.

Library

Enter the name of the IBM i host library where the data queue is located.

Key Order

Select the comparison criteria to use when searching for message keys on the data queue. The keys found are compared to the data in the Key Data parameter. Select from the following:

• Greater than

• Less than

• Not equal

• Equal

• Greater than or equal

• Less than or Equal

When the system searches for the requested key, the entries are searched in ascending order from the lowest value key to the highest value key until a match is found. If there are entries with duplicate keys, the entry that was put on the queue first is received.

Key Length

Enter the length of the Key Data parameter. The Key Data parameter must be zero for non-keyed data queues. For keyed data queues it must be equal to the length specified on the Key Length parameter in the Create Queue method.

Key Data

Enter the data to be used for receiving a message from the data queue.

Error Bytes Available

The length of the error information (in bytes) available for the API to return.

If zero id entered, no error was detected and none of the fields that follow this field in the structure are changed.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Create Queue creates a data queue object on an IBM i server. In IBM i, a data queue is used for program-to-program communication.

A data queue is similar to a database file that has records written to it. One program (or many programs) can send entries to the queue.

Another program (or many programs) can read entries from the data queue. The communication between two programs is asynchronous.

In Magic xpi, you can use the IBM i connector to manage Data Queue objects.

Data Queue Name

Enter the name of the data queue that you are creating.

Library

Enter the name of the IBM i host library where the data queue is located.

Maximum Entry Length

Enter the maximum length of the entry sent to the data queue.

Sequence

Select the sequence that the entries are received from the data queue from the drop-down list.

• FIFO: First in first out

• LIFO: Last in first out

• KEYED: Determined by a special key

Include Sender ID

Select Yes or No from the drop-down list to indicate whether to attach the sender ID to each message sent to the Data Queue. The ID contains the job name and the sender's current user profile.

Maximum Number of Entries

Enter the amount of storage allocated for the data queue. Parameter elements consist of the maximum number of entries and the initial number of entries for the data queue. Possible values are *MAX16MB,*MAX2GB, or a number between 1 and 999999.

Initial Number of Entries

Enter the minimum number of entries that the data queue can hold. Based on the extend size used by the machine, the maximum number of data queue entries may be slightly higher than the value entered. The value must be greater than 0.

Data Queue Text Description

Enter a brief description of the data queue.

Authority

Enter the authority you give users who do not have specific private or group authority to the Data Queue. When the Data Queue is created, its public authority stays the same when it is moved to another library or restored from backup media.

The valid values are:

• *ALL: The user can perform all authorized operations on the object.

• *CHANGE: The user has authority to carry out read, add, update, and delete actions to the object.

• *EXCLUDE: The user cannot access the object.

• *LIBCRTAUT: The public authority for the data queue is taken from the CRTAUT value for the target library when the object is created. If the CRTAUT value for the library changes later, that change does not affect data queues already created. If the CRTAUT value contains an authorization list name and that authorization list secures an object, do not delete the list or the *LIBCRTAUT parameter will fail he next time you call this API.

• *USE: The user can read the object and its description but cannot change them.

• Authorization list name: The data queue is secured by the specified authorization list, and its public authority is set to *AUTL. The specified authorization list must be on the system when the API is called. If it is not found, the create process fails and an error is returned to the application.

After the data queue is created, its public authority stays the same when it is moved to another library or restored from backup media.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Create User Space creates IBM i user spaces, which are a collection of bytes used for storing user-defined information. They are permanent objects that are located in either the system domain or the user domain.

User Space Name

Enter a name for the user space.

Library

Enter the name of the IBM i host library where the user space is located.

Extended Attribute

Enter the user space extended attribute. For example, an object type that is a *FILE type can have an extended attribute of PF (physical file), LF (logical file), DSPF (display file), or SAVF (save file). The extended attribute must be a valid name. When you enter the parameter it is not case sensitive, however the API converts it to uppercase.

Size

Enter the initial size of the user space being created. This value can be from 1 byte to 16,776,704 bytes.

Initial value

Enter the initial value of all bytes in the user space.

Public Authority

Enter one of the following to indicate the authority you give users who do not have specific private or group authority to the user space. The valid values are:

• *ALL: The user can perform all authorized operations on the object.

• *CHANGE: The user has authority to carry out read, add, update, and delete actions to the object.

• *EXCLUDE: The user cannot access the object.

• *LIBCRTAUT: The public authority for the user space is taken from the CRTAUT value for the target library when the object is created. If the CRTAUT value for the library changes later, that change does not affect user spaces already created. If the CRTAUT value contains an authorization list name and that authorization list secures an object, do not delete the list or the *LIBCRTAUT parameter will fail he next time you call this API.

• *USE: The user can read the object and its description but cannot change them.

• Authorization list name: The user space is secured by the specified authorization list, and its public authority is set to *AUTL. The specified authorization list must be on the system when the API is called. If it is not found, the create process fails and an error is returned to the application.

After the user space is created, its public authority stays the same when it is moved to another library or restored from backup media.

Text Description

Enter a description of the user space object.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Create/Update Stream File is used to accept the required parameters to either create a new file or to update an existing stream file. If the stream file already exists, the data is appended to it.

Stream File Name

Enter the name of the stream file.

Input

Enter the data that you want to insert into the selected file.

Code Page

Enter the required code page.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Delete Queue method deletes the a Data Queue from an IBM i server.

Data Queue Name

Enter the name of the data queue to be deleted.

Library

Enter the name of the IBM i host library where the data queue is located.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Delete User Space method deletes data from an existing User Space object on an IBM i server.

User Space Name

Enter a name for the user space that you want to delete.

Library

Enter the name of the IBM i host library where the user space is located.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Program Call is used to call IBM i programs, such as CL, RPG, and COBOL. You can also exchange information between a Magic xpi server and IBM i by sending or receiving arguments to or from IBM i programs. For more information on how to use this method, click here.

Program Library

Enter the name of the program library. This serves as the default library, and is used when no other library path is specified and Magic xpi calls a program.

Program Name

Enter the name of the program being executed. The name can include a path to another library, with the library name first. For example, mylib/runme.

Arguments Number

Enter the number of arguments that are sent to the program. You can have up to 25 arguments.

Argument Attributes String

Enter the argument attribute string. This string contains the input/output information and the argument type and length. The string must be in a specific format. If you are not familiar with how to create this string, you can use the Build Attribute String method to build the string and then enter the variable or parameter where the string is located in this field.

This parameter is mandatory if the Arguments Number parameter is greater than 0.

Arg1 – Arg25

Enter the arguments in these parameters. You must enter the same number of arguments as indicated in the Arguments Number parameter.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Receive Queue Data method receives data from a specified data queue on an IBM i server. The data can be received by any machine in a network.

Data Queue Name

Enter the name of the data queue from where you are receiving data.

Library

Enter the name of the IBM i host library where the data queue is located.

Size of Data Receiver

Enter the size of the area to contain the data received from the data queue.

• A value of 0 indicates that no data is returned.

• A value greater than 0 indicates that data is copied into the receiver up to the specified length.

• If the available data is longer than the length indicated in this parameter, it is truncated.

• If no value is entered in this parameter, the entire message is copied into the receiver variable.

Wait Time

Enter the amount of time (in seconds) to wait before continuing if no entries exist on the data queue.

• A value of less than 0 indicates that the server will wait indefinitely to receive data.

• A value of 0 indicates that the call completes immediately with the length of data parameter set to zero.

• A value of more than 0 indicates the number of seconds to wait. The maximum wait time is 99999, which is approximately 28 hours.

Key Order

Select the comparison criteria to use when searching for message keys on the data queue. The keys found are compared to the data Key Data parameter. Select from the following:

• Greater than

• Less than

• Not equal

• Equal

• Greater than or equal

• Less than or Equal

When the system searches for the requested key, the entries are searched in ascending order from the lowest value key to the highest value key until a match is found. If there are entries with duplicate keys, the entry that was put on the queue first is received.

Key Length

Enter the length of the Key Data parameter. The Key Data parameter must be zero for non-keyed data queues. For keyed data queues it must be equal to the length specified on the Key Length parameter in the Create Queue method.

Key Data

Enter the data to be used for receiving a message from the data queue.

Length of Sender Information

Enter the length of the sender identification.

• 0: No sender information is required

• 8: Returns only the bytes returned and bytes available fields of the sender information.

• More than 8: Return the up to the amount of sender information as indicated in this parameter.

Remove Message

Select Yes or No from the drop-down list to indicate whether the message is removed from the data queue when it is received.

Output Data Length

This parameter receives the number of characters received from the data queue. If a time out occurs and no data is received from the data queue, this field is set to zero.

Output Data

This parameter receives the data from the data queue. The field must contain at least the length of the value entered in the Maximum Entry Length parameter in the Create Queue method. This field contains the data received from the data queue.

Bytes Return

This parameter receives user information about the sender of the data.

Bytes Available

This parameter receives the number of available data bytes that can be returned. All available data is returned if enough space is provided.

Job Name

This parameter receives the name of the IBM i Job that sent the data.

User Profile

The User Profile Name for the job sending the information.

Job Number

The Job Number for the job sending the information.

Current User Profile

This parameter receives the user profile name for the job that sends the data.

Error Bytes Available

This parameter receives the length of the error information (in bytes) available for the API to return.

If zero is entered, no error was detected and none of the fields that follow in the structure are changed.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Retrieve IFS Directory List accepts the parameters that retrieve an IFS directory list.

Directory Name

Enter the name of the directory.

Output Type

Select one of the following output types from the drop-down list:

• XML

• Comma Delimited

Output to File

Click to enter the name of the file in which the directory list will be saved.

Output

Click to select the required output for the directory list.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Retrieve Queue Description method retrieves the description and attributes of a data queue, such as the number of entries currently on the data queue, the text description of the data queue, whether the queue includes sender ID information, and whether the data queue is keyed.

Data Queue Name

Enter the name of the data queue where you are sending data.

Library

Enter the name of the IBM i host library where the data queue is located.

Message Length

This parameter receives the maximum length allowed for the returned messages. This value must match the value entered in the Maximum Length parameter keyword for the Create Queue command.

Key Length

This parameter receives the length, in bytes, of the message reference key from data queues that are of the keyed type. Valid values range from 1 to 256. If the specified queue is not a keyed queue the value is 0.

Sequence

This parameter receives the sequence that the entries are received from the data queue. The valid values are:

• FIFO: First in first out

• LIFO: Last in first out

• KEYED: Determined by a special key

Include Sender ID

This parameter receives a Yes or No to indicate whether the sender ID is included with the data.

Force Indicator

This parameter receives a Yes or No to indicate whether the data queue is forced to auxiliary storage when entries are sent or received for the indicated data queue.

Data Queue Description

This parameter receives a text description for the data queue. The field is blank if no text description was specified when the data queue was created.

Type of Data Queue

This parameter receives one of the following:

• 0: Standard Data Queue

• 1: A DDM Data Queue

Automatic Reclaim

This parameter receives an indication on whether the storage amount is reclaimed after the queue is emptied. The valid values are:

• 0: The storage is not reclaimed.

• 1: The storage is reclaimed and the storage amount is reset to the initial number of entries.

The field receives a 0 for DDM data queues.

Number of Messages

This parameter receives the number of messages in the Data Queue. The value is always 0 for DDM data queues.

Number of Entries Allocated

This parameter receives the number of entries that can fit into a queue before it is extended. When a queue is extended, additional storage is allocated to the queue. The data queue can be extended until it reaches the maximum number.

The value is always 0 for DDM data queues.

Data Queue Name Used

This parameter receives the name of the data queue. This is the same name entered in the data queue Name parameter unless the queue was renamed after the first job accesses the data queue.

Data Queue Library Used

This parameter receives the name of the library where the data queue resides.

Maximum Entries Allowed

This parameter receives the maximum number of entries that fit into the data queue when it is full.

Initial Number of Entries

This parameter defines the number of messages that will fit into the storage allocated for the data queue when it is created or automatically reclaimed.

The value is always 0 for DDM data queues.

Maximum Number of Entries

This parameter defines the number of entries that will fit into the data queue.

Length of Receiver Variable

This parameter receives the length of the receiver variable.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Retrieve Spool File retrieves the contents of a spool file.

Spool File Number

Enter the number of the spooled file.

Spool File Name

Enter the spool file name. This is the same name entered by when the file was created or the device name.

Job Number

Enter the Job number for the job that produced the spooled file.

Job Name

Enter the name of the job that produced the spooled file.

Spool File User Name

Enter the name of the user who owns the spooled file.

Output to File

Enter the name of the file where the spooled results are saved.

Output

Click to select a variable or special user variable to send the content of the spool file.

Visual To Logical

This parameter flips a string from visual format to logical format. Select one of the following from the drop-down list:

• No (default)

• Yes

Print Character

Select one of these print control characters from the drop-down list:

• None

• FCFC

• PRTCTL

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Retrieve Spool List retrieves the contents of a spool list.

Spool List User Name

Indicate the user's spool file to be retrieved. The valid values are:

• All: Retrieves the spool list for all users.

• Current: Retrieves the spool file list for the current user.

• <IBM i User ID>: Retrieves the spool file list for the user whose ID is entered.

Output Type

Select the output type that the spool list is returned in from the drop-down list:

• XML: Returns the spool list in XML format.

• Comma Delimited Text: Returns the spool list as a flat file with the spool file names separated by commas.

Output to File

Enter the name of the file where the spool list is saved.

Output

Click to select a variable or special user variable to send the content of the spool file.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Retrieve Stream File accepts the parameters to allow you to retrieve content from a stream file.

Stream File Name

Enter the file name for the stream file.

Output to File

Enter the name of the file where you want to save the stream file.

Output

This parameter contains the stream file entry's content.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Retrieve User Space retrieves data from an existing User Space object on an IBM i server.

User Space Name

Enter a name for the user space.

Library

Enter the name of the IBM i host library where the user space is located.

Starting Position

Enter the first byte of the user space that is retrieved. A value of 1 will identify the first character in the user space.

Length of Data

Enter the length of the data that is retrieved. This length cannot be less than 0 and cannot be larger than the size of the variable that is to receive the data.

Output Data

Enter the variable that receives the contents of the retrieved user space.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Run Command executes the IBM i command. For an example of how to use this method, click here.

Command

Enter the command to be executed.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Run Query accepts the necessary parameters to retrieve the details of any IBM i database table.

Query Name

The name of the existing query. Enter the name of the library and its query name. The first 10 characters contain the library name, and the second 10 characters contain the query name. They should be separated by a "/".

Query File

The name of the database file that is to be queried. Enter the library name and its query file name. The first 10 characters contain the library name, and the second 10 characters contain the query file name. They should be separated by a "/".

Output Type

Specifies where the report produced by the query is sent. If a value is not specified in the query, or is not entered in the command, or if a query name is not specified, then *PRINTER is the default destination. You can enter one of the following:

• *PRINTER: The output produced by the query is printed.

• *OUTFILE: The output is directed to the database file specified in the Output File parameter (below).

Output Form

The mode of output generated by the query. You can enter one of the following:

• *RUNOPT: If an output form is specified in the query definition, this is used when the query is run.

• *DETAIL: The output form produced by the query is a report containing detail records and summary records if any exist.

• *SUMMARY: The output form produced by the query is a report containing summary records only.

If no value was specified in the query, or no value was entered in the command, or if a query name is not specified, then *DETAIL is the default mode.

Print Definition

Defines whether the query definition is printed with the query report. You can enter one of the following:

• *RUNOPT: If an output form is specified in the query definition, this is used when the query is run.

• *NO: The query definition is not printed when the query is run.

• *YES: The query definition is printed in the report.

Output File

The name of the database file that receives the query output. You can enter one of the following:

• *RUNOPT: If the output destination is specified in the query definition, the output generated by the query is directed to that location.

Output File Library

The library name of the specified output database file. You can enter one of the following:

• *RUNOPT: If specified in the query definition, the output is directed to the library named in the query definition.

• *CURLIB: The current library for the job is used as the location of the database file.

If no library is specified as the current library for the job, the QGPL library is used.

Output File Member

The member name of the specified output database file. You can enter one of the following:

• *FIRST: The first member in the file is used to receive the query output.

• *LAST: The last member in the file is used to receive the query output.

• *RUNOPT: The member specified in the query is used to receive the query output.

• *ALL: The output file is a partitioned table, where all members in the file are used to receive the query output. When *ALL is specified for the member, the Element 3 Data option can only be set to *RPLMBR or *ADDMBR. The partitioned table must already exist when the query is run.

Output File Option

Defines how to handle the data generated by the query. You can enter one of the following:

• *RUNOPT: If a query definition is used, the member option specified in the query definition is the type used when this query is run.

• *NEWFILE: The output is written to a new database file. This option is not valid when the member name is set to *ALL.

• *RPLFILE: The output deletes the old file and creates a new file. This option is not valid when the member name is set to *ALL.

• *NEWMBR: The output is added as a new member. This option is not valid when the member name is set to *ALL.

• *RPLMBR: The existing member is cleared and the output is then added.

• *ADDMBR: The output is added to the end of an existing member.

If no value is specified in the query or in this parameter, or if a query name is not specified, *NEWFILE is the default value.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Send Data to Queue method sends data to the indicated data queue on an IBM i server.

Data Queue Name

Enter the name of the data queue where you are sending data.

Library

Enter the name of the IBM i host library where the data queue is located.

Input Data Length

Enter the number of characters that can be sent to the data queue for the input data.

Input Data

Enter the input data that is sent to the data queue.

Key Length

Enter the number of characters in the key data parameter.

Key Data

Enter the key's data that is sent to the data queue. This value must be at least as long as the value entered in the Key Length parameter, or unexpected results can occur.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.

Update User Space inserts data from an existing User Space object on an IBM i server.

User Space Name

Enter a name for the user space.

Library

Enter the name of the IBM i host library where the user space is located.

Starting Position

Enter the first byte of the user space that is inserted. A value of 1 will identify the first character in the user space.

Length of Data

Enter the length of the data that is inserted. This length cannot be less than 0 and cannot be larger than the size of the variable that is to receive the data.

Input Data

Enter the variable that inserts the contents of the updated user space.

Error Code

This parameter is returned, with the corresponding error code, when an error occurs.

Click to open the Variables List. Select a variable where the error code is returned, and then click Select.