Information

Created By	Knowledge Migration User

Approval Process Status	Published

Objective

Description

System i Connector – Methods

The following methods are used to configure the System i connector:

Build Attribute String
Clear Queue
Create Queue
Create User Space
Create/Update Stream File
Delete Queue
Delete User Space
Program Call
Receive Queue Data
Retrieve IFS Directory List

Retrieve Queue Description
Retrieve Spool File
Retrieve Spool List
Retrieve Stream File
Retrieve User Space
Run Command
Run Query
Send Data to Queue
Update User Space

The following table lists the methods and parameters that can be used. Parameters in bold are mandatory.

Name	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.
	Scale	Enter the number of digits that can appear to the right of the decimal point. This parameter is available only if you selected Numeric or Zoned in the Argument Type parameter (above).
	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 System 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.

How to Use Direct Access Methods

Reference

Attachment

Attachment

System i Connector - Methods (Magic xpi 3.x)

Information

System i Connector – Methods