17 7 The XQ Files

17.7 The .XQ* Files

17.7.1 Tips for Setting up and Using .XQ* Files

Any PC that executes an application using DBID=*ANY, DBID=*AS400, DBID=*OTHER, DBID=*NONE or DBII=*NONE needs to have a special set of additional files created or installed on it, or available to it via a connected server disk drive.

These files are called the "xq*" files and are accessed by your generated Visual LANSA application(s) when users perform actions such as prompting, display help text, etc.

Values *NONE, *ANY, *AS400 and *OTHER are identical in indicating that no local DBMS system is to be used. The difference is that the value *ANY, *AS400 or *OTHER is used to additionally indicate that an automatic connection to a Server is to be established. The details of the connection are defined by a series of PSXX= parameters which are described in 17.4.12 PSxx Server Parameters.

The .XQ files are used in place of a local DBMS for read-only dictionary/repository access.

The complete set of these files is:

These files are in binary format. They are "read only" files and should not be manually edited with any type of tool.

Failure to observe this rule may lead to application failure and/or unpredictable results.

When created, each set of lx_fnn.xqi and lx_fnn.xqd are a "matched pair". File lx_fnn.xqi is an index and makes direct offset references into the lx_fnn.xqd (data) file. You must always create, ship and install both of the lx_fnn files together as a pair. Failing to observe this rule may lead to application failure and/or unpredictable results.

• The files lx_f61.xqd and lx_f61.xqi are only required if your application uses *MTXT variables.

• The files lx_f05.xqd through to lx_f11.xqi are only required if you use (or have enabled) automatic field level help text generation.

• The files lx_f27.xqd through to lx_f26.xqi are only required for LANSA Open applications (on the Server).

• The files lx_f96.xqf through lx_f60.xqf are only required for applications that require non-default system, partition, and language definitions. File lx_f96.xqf is not used for LANSA for i.

• If connecting to a Server via the PSXX parameters or an INIT function, repository data that is not found locally can be retrieved from the Server, or set to defaults. Theoretically, this means that you can deploy the client side of a SuperServer application with no xq* files. However, there are performance and tailoring setbacks. Refer to PSRR Notes (Primary Server Route Repository) for more details.
  
  Refer to Client/Server Applications in the LANSA Application Design Guide for more details about designing and building client/server applications.

All lx_fnn files are placed into the partition source directory (x_lansa\x_ppp\source). If a file does not exist it is created. If it does, it is cleared of all existing data before the export proceeds.

In execution environments, when a specific file is being read, the x_lansa\x_ppp\source directory is always checked first. If the file cannot be located in that directory, the x_lansa\source directory is checked. This allows flexibility in deployment. For example, different partitions can have their own copy of the message file.

The xq* files may be created on any Windows development system at any time. To do this use the X_RUN command like this:

X_RUN PROC=*SYSEXPORT FUNC=ttttt LANG=xxx PART=ppp .... etc.

The "ttttt" value can be specified as an individual table name (e.g. LX_F03 or LX_F46) or as *ALL. The special value *ALL causes all the output files to be produced.

Once started, the export process displays a standard event log and updates it as the export proceeds. When complete, an "OK" button will appear in the event log window, allowing you to review the messages. When you click on the "OK" button the export process ends.

• The PROC=*SYSEXPORT facility exports the specified file(s) to all enabled environments.

• Where an applicable code page / environment translation file exists, its presence and use will be noted in the messages issued by the *SYSEXPORT facility.

• You cannot use PROC=*SYSEXPORT with DBID=*NONE/*ANY/*AS400/*OTHER. Failure to observe this rule may lead to unpredictable results and/or application failure.

• You cannot use PROC=*SYSEXPORT when the lx_fnn files are in use by another application or user. Failure to observe this rule may lead to application failure and/or unpredictable results.

• For lx_f96 and lx_msg, which are system based, all details are exported. For all other lx_fnn files, only the details from the current partition (i.e. PART=ppp on the X_RUN command) are included.

• The partition based lx_fnn files do not store the partition internally. Therefore they can be used with a different partition name. However, data library and program library values are still stored within the files, and these cannot be changed.

• Normally lx_fnn files are created at the completion of a task / project and included into the packaging and installation procedures of the application. If you are using lx_fnn files and DBID=*NONE/*ANY/*AS400/*OTHER, then you should add their production, shipping and installation procedures to the procedures recommended in the section in this guide that describes the packaging of applications.

• The lx_fnn files are a read-only "snapshot" of the associated SQL based tables. You must remember that they are a snapshot. For example, you may use *SYSEXPORT to export LX_F04 (help text) and then run your application using DBID=*NONE. If you edit the help text via Visual LANSA the change will not appear in applications using DBID=*NONE until the lx_f04.xqi and lx_f04.xqd files are (re)created again. (However, if your application connects to a Server and the repository data exists there, missing information will be retrieved by default, if it exists on the server. Changed information will not be retrieved. Refer to PSRR Notes (Primary Server Route Repository) for more details.

The lx_fnn files will support system initialization, field prompting and help text display in a totally standalone environment. These are the essential elements of being able to execute an application in a standalone environment.

Any other form of database activity will fail unless the I/O operations are "diverted" to a server.

Note that I/O operations also include object lock requests (which may be automatically diverted to the server) and IBM i data area emulations (which must be manually diverted to the server by using the CALL_SERVER_FUNCTION facility). Other Built-In Functions such as SAVE_LIST may also involve database activity and must be manually diverted to the server.

Imagine a function that must perform some activity and give the result(s) back to the caller. For example, it might allocate the next order number, or save a list, etc.

The activity must always be performed on the server.

By structuring the function like this:

function *direct rcv_lsts(<working lists>)

exchange <other information> options(*always)

if *cputype = as400

      <perform required activity> 

else 

       use call_server_function ( ... itself ....... ) 

endif

return

When called on an IBM i this function does its job and receives and returns information via working lists, exchange lists, etc.

When called in a PC application, the function immediately calls itself on the associated server (which does its job and returns the results).

To the program that called this one, the switching to the server (if required) is invisible and immaterial.

By using a more flexible and dynamic switch than "*cputype = as400" a very powerful and dynamic means of switching logic between the client and server could be designed.

User Defined Messages

User defined Messages will not be copied to LX_MSG.XQD / XQI files. Therefore the use of FXQF=*ALL is not recommended in scenarios where you have your own application specific messages. In such cases the use of a message file is required.