easycom for delphieasycomstore.com/data/webhelp/easycom_delphi/easycomfordelphi.pdf · easycom for...

Easycom For Delphi

Introduction

Introduction to Easycom For Delphi

Easycom For Delphi is a complete and powerful AS/400 development set of tools for Delphi. It is an high-level performance middleware to access all AS/400 resources and services in a native mode.

Easycom For Delphi is an integrated database access in the Borland Database

Engine, making the access to AS/400 resources fully integrated with Borland’s Delphi.

The IDAPI driver part of Easycom For Delphi opens the access to AS/400 data

through the standard Delphi components (TTable, TQuery, TDatabase) by using alias definition.

Easycom For Delphi allows other tools included with Delphi, such as Report Smith,

to gain transparent access to the AS/400 data.

Easycom For Delphi includes a full record level access over the TCP/IP protocol.

Easycom For Delphi shields the developers from the complexity of designing and

calling API’s directly.

Accessing data is performed in native mode for all file I/O operations.

Record Blocking is optimized and completely handled in a transparent form.

Access all AS/400 resources in batch mode including executing any command or program on the AS/400.

Communicating with all preexistent COBOL, RPG, CL, and C, in a very simple manner.

Access to stored procedures, data queues, and data areas.

The security and data integrity of the AS/400 is not compromised in any way, offering Delphi developers a secure and reliable high capacity data server.

Easycom For Delphi uses the Easycom engine that was proved over the years as

one of the best integration of visual component access to AS/400 data.

Performance Using Easycom For Delphi, Delphi applications can have complete real time access to

AS/400 resources, without any data replication.

Easycom For Delphi database-related features include Files can be read from, written to and updated whether they are physical, logical or 36 format. In order to provide optimum performance, Easycom For Delphi uses existing

access paths and uses native mode access only.

Delphi programs use logical files as indexes.

No code is generated on the AS/400.

Database integrity constraints are fully respected.

Access to query files.

Setup and query of databases (OPNQRYF, OVRDBF, etc.).

Simultaneous access to multiple AS/400.

File sharing and record level locking.

Access to Commitment Control.

Record Level access to data.

Easycom For Delphi resource-related features include

All AS/400 ressources can be accessed from within Delphi. Programs can be called from within Delphi, parameters can be passed, and the results can retrieve back in the PC environment.

Submit a command and execute on AS/400.

Invoke AS/400 programs and retrieve returned parameters.

Access to data areas and data queues.

Access to AS/400 jobs.

Access to communication APIs.

AS/400 Communication Protocol

TCP/IP TCP/IP is rapidly becoming the new standard in communication for AS/400. It provides better performances and is integrated in Windows NT, so no additional product is required.

Native Mode

All database access is done in native mode for optimum access speed and to minimize resource requirements. Native mode access yields performance, which cannot be attained using DDM (Distributed Database Management), or resource intensive SQL.

Batch Reads

By using batch reads, entire sets of data can be retrieved in a single pass.

Integration

Once the AS/400 side of Easycom For Delphi is installed on the AS/400, nothing else needs to be done on the AS/400.

No programs need to be compiled on the AS/400, no host programs need to be written, and resource usage is minimal.

Easycom For Delphi uses the database description from the AS/400, in real time.

There is no duplicate copy kept on the client station. Data type conversions are done automatically, and access can be in either navigational mode or through SQL.

Delphi developers access data through the standard VCL (Visual Component Library) components, which are connected to a BDE alias.

Applications can simultaneously use data on AS/400 system(s), local files and on other servers.

For example, you could easily create an application using personnel data from the AS/400, sales orders from a Microsoft SQL Server, and commission rates from an Oracle database, xBase DBF or Paradox table.

How does it work ?

Easycom For Delphi is a Client/Server product. The Client running on the PC sends requests and receives results from a Server running on the AS/400.

Server Side

The EASYCOM database engine resides on the server. This proven technology provides a robust and reliable way to reach the AS/400 data.

The EASYCOM engine is capable of supporting multiple simultaneous clients, from multiple simultaneous client surfaces (i.e. : Delphi and Excel).

For further information, please see “EASYCOM Integration and Interoperability”.

Client Side

In 32 bits a native BDE driver is supplied. When the BDE makes a request for data, it goes through this DLL or driver.

If it is a request for data from an AS/400, then that request is dispatched to the EASYCOM server running on the AS/400. Data being returned is passed back in the format expected from the BDE.

AS/400 Extensions

In addition to transparent database access through the BDE, Easycom For Delphi also provides Delphi developers with the ability to:

Issue RPC (Remote Procedure Calls).

Ability to invoke RPG or COBOL routines on the AS/400, and receive a result set.

Full access to the communications API.

Complete control of AS/400 jobs (rights, priorities, etc.).

Communication by data queues.

Access to native AS/400 programs.

EASYCOM Integration and Interoperability

Easycom For Delphi is fully integrated with the EASYCOM communications engine, making all of the advanced AS/400 functionality available to Delphi developers.

This integration allows users to access data using Delphi applications, with simultaneous access by Excel or Word users who are using the same data.

Record-Oriented

Because Easycom For Delphi is record-oriented ; it lends itself well to applications, which require fast performance in a client/server environment.

Co-operative Systems

Because RPC is fully supported, you can achieve tremendous performance gains and reduced network traffic by having your AS/400 developers working with the Delphi developers.

Batch-oriented processing routines could be written to run on the AS/400 and be invoked by the Delphi applications. This optimum approach leverages the benefits of both environments, and maximizes the investment in hardware.

Incremental Phase-in

Because RPC allows creation of co-operative systems, you can start developing in Delphi and call existing routines written on the AS/400, which makes it possible to upgrade systems on a module by module basis.

System Requirements

System Requirements

AS/400 System Requirements

OS/400 version 3.2 or later.

PC connections through an Ethernet, Token Ring, Twinax or SDLC network, with each PC having a single connection point.

PC System Requirements

Pentium processor.

Windows NT, Windows 98, Windows 2000, Windows XP.

32-bit Delphi Developer or Client/Server Edition.

Product features

Functions library (DLL),

Objects library on the AS/400 (EASYCOM Technology),

Examples of applications,

Online help file,

User guide.

Installation Steps

Installation

The installation procedure for Easycom For Delphi is performed from a PC and it has two different parts :

The installation of the PC side.

The installation of the server side on the AS/400.

The AS/400 server side is to be installed once only per AS/400. The following steps will be performed during each side of the installation.

On the PC side :

Creating an '\ACE400' directory.

Adding a sub directory for the examples.

Copy all required files.

On the AS/400 :

Creating an library, default name is 'EASYCOM'

Creating a variety of files in this library.

Requirement to install

The PC station has to be connected to the AS/400 by either an APPC router session (PCS, Client ACCESS, NETSOFT...), or by an access TCP/IP to the AS/400.

For the installation only, the user profile using the AS/400 connection has to be of type ‘QSECOFR' security officer. It is possible to set that profile during the installation steps.

Prior to installing the server side of Easycom For Delphi, the user has to know the type of connection to the AS/400.

Access at 32 bits.

Default user profile.

Name of the AS/400 or its IP address.

Easycom For Delphi installation

The installation is divided in separate independent segments ; updating the client side on the PC, setup the example programs, setup the demos, and the setup of the server side on the AS/400.

The AS/400 server side is to be installed once only per AS/400.

When the product is purchased and the registration card is received, a permanent key to the software is generated.

Installation

If Delphi or any BDE application is running, close it. Then run INSTALL.EXE from the CD.

1. Fill up the appropriate information and follow the menu options.

2. If the server side of the Easycom For Delphi install is initiated, fill up the information regarding this site.

After validation of the connection, the install will transfer the server side to the AS/400.

In case of a failure to complete this step, the user can transfer the server side by selecting the icon from the newly created user group under Windows.

3. After the installation of the server side, the user can run the 'ACE/400 configuration', to verify the connection.

Notes :

1. The time of the installation of the server side could vary from 1 to 30 minutes based on the configuration of the AS/400.

2. If the Job issued on the AS/400 during the installation is in a status SFW (Save File Wait) during a long time, it is normal, just continue to wait.

AS/400 Installation Steps

Installation using TCP/IP is performed with the FTP protocol. In this case a FTP server on the AS/400 is required (for installation process only). It is also possible to install with an APPC router and then switch to a TCP/IP connection.

If you used our FTP TCP/IP Server installation, CFGEACTCP command will be automatically launched. Otherwise, you can launch it by hand. This command will :

Create JOBQ in EASYCOM system.

Create JOBQ in EASYCOM library.

Create the Class : Easycom/EACCLS (*CLS).

Create the sub system : Easycom/EASYCOM (*SBSD).

Start the sub system Easycom with the job EASYCOMD on it.

You can modify the objects generated by CFGEACTCP to tune your system.

The Easycom Jobs will start according to the description Easycom/EACJOBD.

If Easycom/EACJOBD does not exist, the jobs start according to the job description of the user, or according to QDFTJOBD.

By default it uses the priority class EACCLS defined in the installation library.

Notice : EASYCOM is the default library name. It could be changed during installation process.

After each IPL, you have to

Start the Easycom sub system by the command : STRSBS Easycom/EASYCOM

This start can be included in the autostart of your system for next IPL.

You can configure your system to run the jobs in another subsystem. In that case, you have to create a JOBD named EACJOBD in the Easycom library. EACJOBD$ is given as a sample of the JOBD.

In case of troubles :

Check if the EASYCOMD job is running in the Easycom subsystem. This job is started while the EASYCOM subsystem is started.

Once the JOBQ EACJOBQ exists in the EASYCOM Library, this JOBQ must be added to an active subsystem, and the routing data and class have to be configured correctly.

Easycom For Delphi will automatically use the PC station name to identify the job on the subsystem. When the station id is not found then the IP address will be used.

To monitor the jobs executed on the AS/400, operations could be reviewing the jobs in the Easycom subsystem.

AS/400 Activating the Serialization key

From the EASYCOM program group, select and launch the EASYCOM Configuration.

Fill the following boxes :

AS/400 Name

Default System

Machine Name or TCP/IP address Select the default system if you are using a single AS/400, or select and fill in the Machine Name.

If the router is not connected by default to the AS/400 you want to use with Easycom For Delphi, you need to set the correct name. If you are using SNA Server, the AS/400

is known by its alias name, defined in the SNA Server configuration.

Server Program

Default (EASYCOM/EASYCOM)

Other Select the default system or type in the library name you want to use. You can use a library name other than EASYCOM.

This information will be stored in the EASYCOM.INI file.

Click on the connect button.

If the connection is successful, the connect button will be disabled and the registration button enabled.

If you receive an error dialog box like "EASYCOM.DLL Router not installed", you are experiencing a connection error and you must retest all aspects of your connection.

Notice : You can check what version of Easycom For Delphi you are using. In the main windows of the Easycom serialization you have a Version section.

Into Easycom For Delphi build 3.1, you get :

Easycom Server : 4.58.68

Delphi Installation Steps

There are no specific installation steps required for Easycom For Delphi.

A new alias named “ACE400” of type ACE400 is created. Set the “library name” to the library name in the AS/400. Depending on the options selected during during setup, "ACE400" and "EASYCOM" component tabs will be created in the tool palette. If Delphi 2005 is used and the corresponding option is selected a BDP Driver will be installed (see "The Easycom BDP Driver" section).

Easycom For Delphi program protection

In some situations, protection is not made on AS/400 files, but on AS/400 programs (some users will be only able to use some programs).

This will allow to restrict the access of the AS/400 to a specific selection of PC programs. This restriction is configured on the AS/400 side.

In other words : by giving the right password(s) to the right developers, you can avoid unauthorised developers to write unauthorised programs.

So, you can set-up a controlling program that will receive the EAC_UNLOCK value in a parameter. So, application that do not know the appropriate value, will not be able to use ACE/400.

Here are details on how to use this feature.

You can do the following steps :

Step1 : Configure EASYCOM server in a LOCKED mode

It is done with the CFGEAC command on AS/400.

Do :

CHGCURLIB EASYCOM

CFGEAC

It will show you the following screen :

Easycom server library name EASYCOM

Easycom server job priority 0 TCP/IP Keep Alive frequency 120 Delay before asking again pwd 0 Delay before automatic SIGNOFF 0

Easycom Log File level 0 Print the clock in Log File *NO

Automatic Keep Alive start *YES

Detailed Job Log *NO

Lock Easycom host *YES

If the option ‘Lock Easycom host’ is set to *YES, by default no files can be accessed and no AS/400 programs or commands can be executed. The Easycom server can be unlocked remotely by a password sent by the PC application.

Step 2 : Make a validation program

When the password is sent from the PC, the Easycom server will call a program named EACP003 in *LIBL.

Here is a sample on how to make the validation program.

PGM PARM(&PASSW &RESULT)

DCL VAR(&PASSW) TYPE(*CHAR) LEN(100)

DCL VAR(&RESULT) TYPE(*CHAR) LEN(10)

…

/* IF PASSW HAS THE RIGHT VALUE */

CHGVAR VAR(&RESULT) VALUES('*YES')

…

/* IF PASSW DOES NOT HAVE THE RIGHT VALUE */

CHGVAR VAR(&RESULT) VALUES('*NO')

Step 3 : Put the password in your Delphi Application

Use the EAC_UNLOCK option to put the right unlock password. You can set-up this option using the TDatabase component in your application.

Because EACP003 is called by EASYCOM, you also can control the current user (by a RTVJOBA in EACP003). You also can decide to assign an unlock password for a set of users.

You also can decide to use a different password for each PC application. Doing this you can decide in the EACP003 program if a particular user can use a particular program (because the password will identify the PC program).

Important note :

Be aware of TBatchMove component limitations.

TBatchMove does not create indexes for the destination table, and field types are automatically matched with source field types, which can lead to problems trying to create non-supported field types in the AS/400 or transferring empty date fields.

You will probably use native AS/400 tools to create and manage AS/400 tables, but we wanted to provide you with maximum compatibility with existing Delphi components.

Easycom For Delphi Connectivity options

The Easycom IDAPI Driver

The Easycom IDAPI Driver

The Easycom IDAPI Driver is the first, and probably easiest way to access AS/400 data and programs using Easycom.

The IDAPI Driver support is possible from any Delphi, C++Builder, C#Builder version (except Delphi 1-can be obtained on specific request), and any 32 bits application using the BDE.

However, the IDAPI Driver is not supported by Kylix. With Kylix, you can use the dbXpress driver or our native (without BDE) components.

Using the IDAPI Driver is done from the Tdatabase, Ttable, Tquery, ... compoenents. Those components can be found in the "Database" or "BDE" tab, depending on the Delphi version you are using.

Alias configuration options

These are main configuration options.

These options can be changed at 3 different levels:

At the driver level. At the alias level. In a TDatabase component of the application.

SERVER NAME

This is the name (or IP address) of your AS/400. It is possible to change it at run time, and connect to multiple AS/400 at the same time.

NETWORK

It represents the network type to use to connect to the AS/400.

If blank, the default value is taken from ACE/400 configuration.

Other possible values are:

Tcp for TCP/IP.

ehn for all EHNAPPC routers (like Client/Access, Netsoft, ...).

sna for Microsoft SNA server.

LIBRARY NAME

This is the default working library. If in your applications you don’t name the library, the value will be the default one.

Valid values are:

any existing library name on your AS/400

*LIBL

*USRLIBL (default)

*CURLIB

BROWSE LIBS

During design time, a special dialog box prompts allowing you to browse the files of your AS/400.

If you don’t want to see this dialog box, change this option to FALSE. The files will be the files of the library specified by ‘LIBRARY NAME’ option.

Default value is TRUE.

CODEPAGE FILE

This is the name of a codepage file, to allow custom EBCDIC-ASCII conversions.

In most cases, you will NOT need to fill this setting. The appropriate code page will be automatically chosen by analyzing your PC and AS/400 configuration.

Be careful : You must specify the FULL PATH of the file.

The code page files are provided in the "international pack".

If you don’t have the codepage file and for Korean/Japan/China countries please install the International pack to have appropriate conversion pages.

To know which is the codepage file for your AS/400, make a DSPSYSVAL QCCSID on a green terminal.

C:\Program Files\EasycomINT\e285ansi.cpg

CONVERSION RULES

This parameter allow to customize field conversion rules.

It contains a list of rules separated by a semicolon.

Possible rules are :

LONGNUM=

By default, a number (PACKED or ZONED) that cannot fit a double is converted to characters. With this option, it is converted to a double (and can lose precision).

LONGNUM=

With this option, big numbers will be converted to Delphi BCD type. But unfortunately most visual components do not support this data type.

LONGNUM=

With this option, big integer numbers will be converted to Delphi 64-bit integer.

This option can be combined with other (for example CONVERSION RULES=

By default this option is enabled from version 5.0 of the BDE (disabled is other cases).

LONGNUM=NOCOMP

SMALLPACK=

By default, a small packed or zoned field (under 5 digits with no decimals) are converted to the Delphi type ‘smallint’. When setting this option, it makes these fields to be converted to integers.

Example of use :

CONVERSION RULES=

CMTCTL

Set it to TRUE if you want to work with transactions.

You will be able to use BeginTransaction. Default is FALSE.

EACUNLOCK

This option allows advanced protection of your Client/Server programs.

See section 'Easycom For Delphi program protection' for more information.

LANGDRIVER

This is the default language driver for your PC. Default is ANSI.

LOCKTYPE

This option is used to choose the way of locking records when using physical/logical file accesses.

Two possible values are :

PESSIMISTIC (default)

With this value, the record is locked during the whole process of editing a record.

For example, with Delphi the record is locked with the Table.Edit and release with Table.Post.

So if different users try to modify the same record, other users must wait for the record post.

OPTIMISTIC

With this value, the record is only locked when trying to update the record.

If the record has been modified by another user since the Table.Edit, the update is canceled and a Bde exception is raised.

LOCKTYPESQL

This option is similar to LOCKTYPE, but is application to SQL queries.

With SQL, when using this option with 'OPTIMISTIC' setting, SQL statements will always be opened read/only. Updates, Delete and Insert orders will be performed by separated SQL statements. Default value is PESSIMISTIC.

PRIVATE SESSION

Set it to TRUE if you want that each connection (by a Tdatabase Component) must be one different connection on the same AS/400.

Default is FALSE.

LOG LEVEL

This allows you to make a text trace of operations that are made by the server. If 0, no trace is made.

Default is 0.

LOG FILE

Represents the file on the AS/400 that will be created if LOG LEVEL is not zero.

OPTIONS

This is the general-purpose alias option.

The syntax of the value is a semicolumn-separated list.

Example :

LOCALFILTER=

Supported suboptions are :

CRTTABLE SCRIPT=

This option creates an SQL script for tables and index creation. With this option enabled, all file creation will be performed with SQL (otherwise we will use DDS in case of non-using of long table names).

<path> is the name of the script file to create.

LOCALFILTER=

This option allows a local processing for filters. It is a useful value if the application filters only small files. It means that all data (non filtered) will be transfered on PC side, and then filtered by the ACE400 driver.

Otherwise, the filters will be performed on the AS/400 side (by an OPNQRYF). With server-side filters (default behavior), only one filter at a time is alowed for each access path (physical/logical).

Note : you also can set-up this option for each file with the PROPERTIES options. Default value is FALSE.

DEFAULTNULL=

This option allows to have null values by default for each field. Otherwise, you will get blank values for each field (except for a Date field that will get null if the field is null-capable or 1/1/0001 if not null capable).

This option will have an effect only on Null-capable fields.

Default value of this option is FALSE.

USEALIASES=

By default, ACE/400 will use field alias names as long field names. This provides a easy migration for an SQL application to an ACE/400 application.

But for backward compatibility purposes, you might want to not use the alias names (and then use the regular 10 digits field names). You can set this option to FALSE to do this.

Default value for this option is FALSE.

CACHEDSQL

This allows to have a local SQL (or storedprocedure) result. This make multi-selection easier, and prevents for unwanted refresh.

The syntax is :

CACHEDSQL=

n is the upper limit of the number of rows that we can hold in memory for a query.

ALL value means no limit.

m is the number of rows that we can read in one time. Default is 32kb of data.

MIN means that m cannot be greater.

MAX means that is m is a too small value (less than 32Kb of data), the value will be increased to have 32kb of data. Default is MIN is m is specified.

Here are sample of syntaxes :

CACHEDSQL=ALL ==> queries and stored procedure resulsets will be hold completely in memory (if the use pushes the 'LAST' button). Data will be fetch by 32kb of data.

CACHEDSQL=ALL, 100 ==> queries and stored procedure resulsets will be hold completely in memory (if the use pushes the 'LAST' button). Data will be fetch by 100 records

CACHEDSQL=ALL, 100, MAX ==> queries and stored procedure resulsets will be hold completely in memory (if the use pushes the 'LAST' button). Data will be fetch by 100 records or by 32kb of data if the record size is small

CACHEDSQL=10000, 100 ==> queries and stored procedure resulsets will be hold completely in memory (if the use pushes the 'LAST' button). Data will be fetch by 100 records. If there are more than 10000 rows in the result, the cached SQL will abort, and dynamic SQL will be used instead.

This CACHEDSQL parameter is in the 'OPTIONS' BDE parameters. So you can have :

OPTIONS=

If you want to combine Cached and nonCached queries, you need to define two Tdatabase components (the connection can be shared).

If you define a 'PESSIMISTIC' requestlive query, the option will have no effect.

JOBNAME=

BIGPARAMTYPE=

VARLENGTH

This option allows to customize AS/400 Variable Length fields handling.

If you put ‘VARLENGTH=MEMO’, it will convert it to Delphi’s memo fields.

By default, it will convert it to simple Delphi’s string fields.

STOREDPROC=

SQLCAUSISTANTBM=

Traitement supplémentaire pour une meilleure stabilité des DBGrid, au mode multi-selection.

Misc. configuration options

Additional configuration options are provided, for special behaviors.

Some of them are only provided for backward compatibility with LightLib/400.

These options are in easycom.ini file.

- Oldconversion, in [general] section. This allows to use old conversion behavior that was in LightLib/400. The numeric fields (packed or zoned) will always be converted into double values or character values (if above the precision of double). Put Oldconversion=1 to enable this. Default is 0

- ThreadAttach in [Multithread] section and NbSession in [NT] section.

By default, with multithread, the AS/400 connections are shared with the threads.

To automatically generate one connection per thread, add in easycom.ini file:

[MultiThread]

ThreadAttach=

[NT]

NbSession=

Default is 0 for ThreadAttach and 1 for NbSession.

Nbsession is the maximum number of AS/400 connections. It can be illimited (but allocates some more memory).

Because most of APPC routers are not thread-safe, Multithreading is only safe and supported on TCP/IP.

Connections

Testing Data Access

Before running the Easycom For Delphi samples, you must be sure your PC is properly connected to the AS/400.

If you were able to run the EASYCOM installation and transfer files onto the AS/400, this can be taken as a good sign, but it's not a guarantee.

You could still experiment connection errors, depending on the setup of drivers and the AS/400 communications layer.

Launch Delphi. Create a New Application.

Drop a TTable component onto the main form.

Set the DatabaseName to ACE400.

Set the Table Name to SP_CUST in the EASYCOM library using the Dialog. Once you select it, a "real" connection will be established to the AS/400, which could take a while. When prompted for a Database password, press enter.

Note : The dialog fills the combo box list of the Table Name property. Once this is done, you still need to select one of the items.

Set the Active property to True.

Drop a TDataSource component and connect it to the TTable.

Drop a Grid component, connect it to the DataSource, you should see the AS/400 data in the grid.

If you have been successful with these steps, then congratulations, you have just created your first Delphi AS/400 application ! You are ready to move on and do some real work with the AS/400 and Delphi. But first, we would suggest that you first take a look at the sample applications provided with Advanced Client Easycom/400 for Delphi.

Please notice that the Logical files associated to a physical file are visible in the IndexName and IndexFields.

If you did not get data displayed in a grid, then there's no point in trying the samples as they will fail.

Carefully check all of the installation steps, on the Delphi side (aliases ...), then, on the AS/400 side, check if you are receiving any error messages, and check the connectivity layers.

Use the Benchmark and Serialization programs to retest communications.

Field type management

All kinds of AS/400 field types are supported. For the field types that don't exist on AS/400, they are converted to the nearest field type.

Null capability is also fully supported : you can get or set null field information with tables and queries. You can even make a key search with null values.

Depending of the AS/400 type of a field, it is converted (in read and write) to a PC type. Conversion between AS/400 types and PC types are made by the client.

The conversion map follows :

AS/400 type Size Dec PC Type

You can notice that PACKED or ZONED fields are optimally mapped to a type depending on the size.

From Bde version 5 PACKED or ZONED field that have no decimal but a number of digits between 16 and 18 are mapped to 64 bits integers.

Easycom For Delpi Properties

You may want to set-up special properties for particular AS/400 files.

Having a TTable, a TDatabase or TQuery component, some additional properties can be set-up.

You will use DbiSetProp/DbiGetProp with the Handle property of your component.

For example :

DbiSetProp(hDBIObj(Table1.Handle), curNRECORD, 50) ;

Current available properties for TTable/TQuery are :

const

dbCONVRULES = $0404ACE5 ;

curNRECORDS = $22050000 ;

curLOCALFILTER = $22050001 ;

curLOCKTYPE = $22050002 ;

dbCONVRules value is used to change conversion rules.

This as the same features as the CONVERSION RULES option of the ALIAS.

Current possible values is a combination of integers :

const

CONVR_LNUM_DOUBLE = 1 ;

CONVR_SMALLPACK_INTEGER = 2 ;

CONVR_USEBIG_BCD = 4 ;

CONVR_COMP = 8 ;

CONVR_LUM_DOUBLE conrresponds to LONGNUM=

CONVR_SMALLPACK_INTEGER conrresponds to SMALLPACK=

CONVR_USEBIG_BCD conrresponds to LONGNUM=

CONVR_COMP conrresponds to LONGNUM=

curNRECORDS is used to change default number of records that are used for internal cache. Default value is 30.

CHAR Any ZString (pChar)

BIN2 INT16

BIN4 INT32

PACK or ZONED

1->4 0 INT16

PACK or ZONED

5->9 0 INT32

PACK or ZONED

10->15 Any DOUBLE

PACK or ZONED

Other cases

ZString (pChar)

DOUBLE DOUBLE

FLOAT DOUBLE

DATE DATE

TIME TIME

TIMESTAMP DATETIME

curLOCALFILTER corresponds to LOCALFILER=TRUE in the OPTIONS ACE/400 option alias.

curLOCKTYPE corresponds to the LOCKTYPE and LOCKTYPESQL alias options.

value 0 correponds to PESSIMISTIC (default)

value 1 correponds to OPTIMISTIC

Specific Components

Components of Easycom For Delphi

The components on the ACE/400 of the Component palette make specialized AS/400 access functionality available to your Delphi applications.

All standard database tasks are performed with the native AS/400 driver ACE400. These components are designed for AS/400 specifics purposes only.

ACE400Rrtv

Description

This component allows AS/400 commands that returns a value, such as Rtvsysval.

From your application, you can send a command to your AS/400, and receive values from the command.

How to use

Step 1 : Fill the Command property. It can contains some variable declarations.

Step 2 : Run the execute function.

Step 3 : Examine the resulting variables with FieldByName method.

Example : Retrieve a Data Area value

JobRcvMsg.command:=

JobRcvMsg.execute;

MsgToSendToJob.Text:=

Properties

Command

property Command:TStrings;

Description

This property holds the text of the command. It can also contain declaration of variable types and sizes.

Here is the general syntax :

<decl1>;<Decl2>...;<Decln>;MYCOMMAND &PARM1 (&Decl1), ....

Each item are separated by a semicolumn. Declarations can have the form :

NAME=

or NAME=DEC(xx yy)

Default type of a variable is CHAR. You must specify a size of a character variable if it exceeds 20 characters.

Fields

property Fields[index:integer]:TACE400Field;

Description

This function is used to retrieve result value(s).

CommandText

property CommandText:string;

Description

This property has the same purpose as the Command Property. It is an easiest way to setup the command at run time.

For syntax of the command, see description of Command Property.

Methods

Execute

procedure Execute;

Description

This function executes the command.

If the execution fails, it generates an exception.

FieldByName

function FieldByName(const FieldName:string):TACE400Field;

Description

This function is used to retrieve result value(s).

This allow an easy access to values, like this :

Result := MyACE400Rtv.FieldByName('MYVAR').AsString;

ACE400RCmd

Description

This component allows remote command to the AS/400.

How to use

Fill ‘Commands’ property with the commands (one command each line). Then call ‘Execute’ method.

The execute function will return the number of succeeded executed commands.

Example of use

{ Add libraries in the LIBL with TACE400Rcmd Component }

ACECmd..Commands.Clear;

ACECmd.Commands.Add(‘ADDLIBLE MYLIB1’);

ACECmd.Commands.Add(‘ADDLIBLE MYLIB2’);

If ACECmd.Execute <> 2 Then

begin

// error

end;

Properties

Commands

property Commands:TStrings;

Description

This property holds all the commands you want to send the AS/400.

Each item of this property represents a command.

NoWaitObject

property NoWaitObject:TOleControl;

Description

This property is used to link the component to an TACE5250 component.

This is useful when having an ACE5250 terminal component running in the same job than easycom.

This allow to have end notification in TACE5250 component after having used TACE400Rcmd.ExecuteNoWait.

StopOnError

property StopOnError:boolean;

Description

This property is useful only if you plan to put multiple commands in the component.

If this property is true, the component will stop processing if one command fails.

Otherwise, it will ignore all commands failing.

The number of successfully executed commands is returned by the TACE400Rcmd.Execute method.

Methods

Execute

function Execute:integer;

Description

This function executes the commands that are in Commands property. It returns the number of the commands that were successfully executed.

ExecuteNoWait

procedure ExecuteNoWait;

Description

This procedure executes the command that is in the Commands property (for this function, only one command is allowed).

It is designed to be used only in conjunction with a 5250 emulation component.

It can indeed handle interactive commands (such as WRKACTJOB).

This only can work if the 5250 terminal is working in the same job than your client/server application.

The function returns immediately without waiting command completion.

All BDE components using the TACE400Rcmd.DatabaseName are unavailable during command processing :

only the 5250 is useful there.

End notification will be sent to the 5250 emulation component by TACE5250.RcmdComplete Event.

The 5250 component that will recieve notification must be linked to the TACE400Rcmd component using

TACE400Rcmd.NoWaitObject property.

Steps to follow to use this function :

- fill TACE400Rcmd.Commands with your interactive command

- point TACE400Rcmd.NoWaitObject to your TACE5250 component

- make your 5250 working in the same job (by using Easycom Protocol or by using EACHOST).

- point TACE5250.DatabaseName to the same alias than your C/S application.

- use TACE400Rcmd.ExecuteNoWait

- show your 5250 window to let the user work with it

- intercept the TACE5250.RcmdComplete Event to show again your C/S application.

ACE4Tbl

Description

This component is essentially a design-time component.

It allows to update the 'DisplayLabel' properties of a TTable component to be update from the column headers.

How to use

Put a TTable linked with ACE/400 on the Form. Connect it to an AS/400 file that has column h headers in it (you can check it with a DSPFFD on the file). Use the field editor of the TTable to add the fields you want to use with the file.

Then put a TACE400Tbl component on the form. Link it to the TTable component. Then double-click on the TACE400Tbl component, and all the display labels are updated !!!

At the end, the component can be deleted, or used to update another TTable component.

Properties

ACEDataSet

property ACEDataSet:TDBDataSet;

Description

This property points to the TTable component that will be updated.

Methods

UpdateFields

procedure UpdateFields;

Description

This function is used to update the display labels at run time.

ACE400ObjListTable

Description

This component allows the listing of AS/400 objects.

Typical application is listing files. However this component can be used to list any type of AS/400 objects.

How to use

Fill all the properties (don't forget the DatabaseName property). Then link the component to a TDataSource, and then to a data component such as a TDBGrid.

ACE400FieldListTable

Description

This component allows to get full information about AS/400 fields.

It will retrieve full AS/400 information, such as column headings, AS/400 types, ...

How to use


Properties

FldFile

property FldFile:string;

Description

This property holds the AS/400 file name.

FldFormat

property FldFormat:string;

Description

This property holds the object format to examine.

Possible values are :

- a Format Name

- *FIRST for the first format.

FldLibrary

property FldLibrary:string;

Description

This property holds the AS/400 library name. This value can be *LIBL or a full qualified library name.

ACE400SpoolListTable

Description

This component allows the listing of spool files.

How to use


Properties

SplUserName

property SplUsername:string;

Description

This options allows to filter the user name. This can contain a user name, or *ALL.

SplOutputQueueName

property SplOutputQueueName:string;

Description

This parameter specifies the AS/400 Output queue name. This can be for example QPRINT, *LIBL/QPRINT or any queue name.

SplFormType

property SplFormType:string;

Description

This property holds the form type selection. A value for this parameter can be for example *STD or *ALL.

SplUserSpecData

property SplUsername:string;

Description

This options allows to filter the user special Data. This can be any value or *ALL.

SplFullFormat

property SplFullFormat:boolean;

Description

The listing can have two formats. If this property is true, the result will include all the fields.

If this property is false, the result will only include the first 7 fields.

ACE4Call

Description

This component allows to call AS/400 programs. This can also be done with TACE400Rcmd or TACE400Rrtv, for simple calls.

This component is inherited from TStoredProc Component.

This component allows full-feature remote procedure call.

To call a program, proceed in 3 steps :

1. At design time, describe the procedure call.

2. At run time, prepare the call (it will bind the parameters definition).

3. Setup input parameters and call execute method.

The step 3 can be iterated as needed.

ACE400Usr

Description

This component allows to change current user at run time.

How to use ?

Step 1 : Fill the username and password

Step 2 : Put the active property to true.

Be careful: To enable this property, you must provide access rights to the objects QSYGETPH, QWTSETP, and QSYRLSPH.

By default this objects are only accessible to QSECOFR and QSYS users. Change the rights of this objects only if you need to use this component.

Properties

Active

property Active:boolean;

Description

This property triggers the user change. If it fails, it will throw an exception. If it succeeds the current right will belongs the users specified by the UserName property.

Password

property Password:string;

Description

Specifies the password of the user to change to. Be careful, if you fill this property at design time, the password will appear in clear during development.

This property can of course be used at run time (just after the Database connection).

Username

property UserName:string;

Description

Specifies the username to change to.

The Easycom Native (without BDE) components

The Easycom Native (without BDE) components

The Easycom Native components are visible on the "EASYCOM" tab in the tool palette.

Those components are available in Delphi 6 and Delphi 7 (not in Delphi 2005), and also in Kylix 3.

Those components are not using the BDE stack level, but have a specification very close to the BDE components: Ttable, Tquery, ...

The deployment is much more easier than with the BDE.

However some limitations are implied, compared to the BDE components. This includes the AS/400-only connectivity, and some disabled features.

So using those components is a good solution when building an AS/400 only application is needed, and when :

the BDE deployment is a problem,

a Kylix portability is required

This solution is to be compared to the dbXpress driver solution, because of the Kylix portability issue. In fact, those components are easiest to use and have more native-only features (like SetRange, GotoKey,...) and is really different from the dbXpress approach which is "submit query/storedproc- get all results".

The class names are different. When you have "TTable" in the bde components, you will have "TEacTable" with Easycom. TACE400Rcmd becomes TEacRcmd, and so on.

However, the property and method names are identical. So porting a BDE application to those components is an easy task.

The BDE administrator as been replaced by a simple, not mandatory, .ini file. This .ini file will contain the same information that were in the BDE aliases. Here are the default .ini file contents :

;

; EasycomAlias.ini

;

[Aliases]

Alias1=

[EasycomAlias]

OPTIONS=

SERVER NAME=

So you need to fill an "AliasXX" entry in the [Aliases] section, and fill all the properties you want.

To have the documentation for TEacTable, TeacQuery, TeacStoredProc, TeacSession, TEacDatabase, TEacUpdateSQL, please refer to the Borland documentation.

For documentation on the other components (for more AS/400 specific tasks), please refer to the "Components of Easycom For Delphi" help section.

Easycom For Delphi Native Components deployment

For the deployment you can avoid the usage of the .ini file (this is recommended), and use the "DriverName" property of a TEacDatabase component.

You will need to deploy only the following files :

EasycomIdapi.dll (our BDE replacement)

Easyco32.dll

Easyco32.fr (for French support of Easycom dialog boxes).

Eac32tcp.dll

Easycom.bpl (if the project is built with the runtime packes)

You also might want to deploy the easycom ini file (EasycomAlias.ini and Easycom.ini), and the Easycom configuration tool (EacCfg.exe), but it is not mandatory.

The Easycom dbXpress driver

The Easycom dbXpress Driver

Easycom For Delphi includes a dbXpress driver.

Using a dbXpress drivers advantages are :

light database components.

easy deployment.

Kylix portability (our driver is maintained on Kylix as well).

The Easycom For Delphi dbXpress driver can do the following :

open queries with parameters, and fetch all data sequentially with high performance.

Call native or SQL programs on the AS/400, and retrieve result parameters or result sets.

Can open and fetch all records of a physical or logical files.

So the driver specifications have no direct key-level access, but is completely SQL-oriented. The approach of a dbXpress application is to submit a query or a stored procedure, get the results, and work on it locally.

Deployment of an Easycom For Delphi application using the dbXpress driver will require the following files :

EasycomDbx.dll

Easyco32.dll

Eac32slf.dll

Easyco32.fr (for French support)

Eac32slf.fr (for French support).

The Easycom BDP driver

Introduction

The Easycom BDP driver is a transparent connectivity method to access the AS/400 resources that fits the BDP standard.

Because it relies on the .NET technology (the BDP Driver is a .NET assembly) the BDP connectivity is available in ASP .NET, and Windows Forms (.NET) application types.

The Easycom For Delphi BDP Driver is available for Delphi 2005 (Delphi 8 is not supported).

For VCL Forms application types, you need to use other connectivity technologies (BDE or dbXpress).

Using the Easycom BDP Driver

You can use Easycom with the Delphi BDP components just by selecting the Easycom BDP connection. For example, you can select the “Data Explorer” windows (available with the View/Data Explorer menu option).

Then you can option the default connection entry (“EasycomConnection”), log-on and see the file list of the user’s library list (*LIBL).

Easycom BDP Driver options

Using the “Data Explorer” window, you can configure some default values for the developer.

Use the “Modify” context menu option on the “EasycomConnection” entry to modify a connection, or use the “Add New connection” context menu option on the “Easycom” entry to create a new connection definition. You can for example create a connection entry for each AS/400.

Each connection can have its own parameters including the user, password, machine name, and so on.

The parameters are classified in four sections. Here is the meaning of the parameter values.

“Connection” Section

Server : The name or the IP address of the AS/400

UserName : The user profile. In interactive environment, if this parameter is omitted an Easycom dialog box will be shown. If this parameter is omitted in a service (for example in ASP.NET environment) an exception will be thrown during the connection.

Password : The password that belongs the username.

JobName : The job name to use. By default this is the name of the PC.

Pooled : Choose if pooling or not this connection object. See 'Pooling connection' topic for more details. Possible values are 'True' and 'False'. Default is True.

PoolLimit : Determines the limit of using pooled connection. When the limit is reached the thread will wait until a pooled connection is available or until the timeout is reached (see PoolTimeout parameter and 'Pooling connections' topic for more details). Non-pooled connections are not counted with this parameter. This value is an integer representing the maximum number of connections being pooled. Default is 0 (unlimited).

PoolTimeout : Represents the maximum number of seconds to wait if the pool limit is reached. Default is 0 (unlimited).

Shared : Choose if sharing the connection for the same thread. Possible values are 'True' and 'False'. Default is False.

Init Libl : Some libraries to add to the default library list (that belong to the user ID). This is a semicolon-separated list, like "MYLIB1;MYLIB2".

“Connection Options” Section

LoginPrompt : Set it to true to see the BDP login prompt. The Easycom loginprompt can appear anyway if the connection options are incomplete.

QuotedObects

TransactionIsolation

You can set the isolation level for each transaction. Possible values are:

o ReadCommitted : The transaction imposes a shared lock which restricts the reading of modified data. You can, however, change the data before the end of a transaction. This action results in non-repeatable reads or phantom data.

o RepeatableRead : The transaction locks all data in a query, preventing any updates to that data. Using this isolation level eliminates non-repeatable reads, but can still result in phantom data.

o DirtyRead : No exclusive locks. Any other user can read and write

to data that has been changed prior to committing.

o Custom : This is an unknown value. By default, the isolation level is the same as the calling component's isolation level. If the calling component is the root component, this value is set to Serializable.

“Options” Section

EacUnLock : A special password that can be validated by a user-defined AS/400 program. This avoids to non-authorised developers to use Easycom. See 'Advanced security features' in the server documentation.

CodepageFile : designates an ASCII-EBCDIC translation file. This is mostly useful for DBCS countries like China, Japan, Korea.

ShortFieldNames : tells Easycom to use only short forms for field names. This will ignore aliases of columns. Valid values are 'True' and 'False'. Default is False.

SqlNaming : Choose between '.' and '/' to separate files and libraries. When using '.' the library list is not available (and current library is the name of the user). Possible values are '/' and '.'. Default is '/'.

Easycom BDP Driver deployment

The deployment of an application that uses our BDP driver will require to deploy the following files :

Borland.Data.EasycomBdp.dll - the Easycom BDP driver assembly

Easycom_Core.dll - the Easycom core file

Easyco32.dll

Eac32slf.dll

Easyco32.fr - french dialog boxes

Eac32slf.fr

Easycom BDP Driver standard classes

The BDP driver is a set of .NET classes that are in the Borland.Data.EasycomBdp namespace.

The available classes are :

EAConnection : represents a connection.

EAConnectionString : manages the connection options.

EACommand : prepares a command (file, query, or program call).

EACursor : used to read data.

EAMetaData : used to list objects (files, queries, programs).

EAResolver : used to build queries (update, insert).

You don’t need to use those classes directly, but you are using the classes that are in the “Borland Data Provider” category in the tool palette.

BdpConnection, BdpCommand, BdpDataAdapter, BdpDataReader are the main classes.

BdpCopyTable is currently not supported.

See the Borland documentation for more details on how to use the BDP classes.

EASYCOM native classes

Introduction

In addition to the BDP driver, some native classes are provided. Those native classes are in the

Borland.Data.EasycomBdp assembly, but in the Easycom namespace.

EasycomConnection

EasycomConnection Class

Namespace Easycom

Syntax

[Delphi] type EasycomConnection = class (System.Object);

Description

The EasycomConnection class represents a physical connection to the AS/400. Because this connection can be "pooled", when you close the object (using .Dispose() or .Close() method) the physical connection may remain.

The BDP driver class “EAConnection” is using the EasycomConnection class internally to handle the connection (the EasycomConnection method of the EAConnection class returns a reference to the EasycomConnection internal object).

A typical use of EasycomConnection object consists of filling the “ConnectionString property”, and call the “Open” method.

Example of use

var my_cnx:EasycomConnection;

my_file:EasycomFile;

result:string;

begin

my_cnx := EasycomConnection.Create;

my_cnx.ConnectionString := 'Server=194.206.160.111;User Id=

my_cnx.Open;

my_file := my_cnx.OpenFile('S_CUSTOMER');

if my_file.ReadKey(2156) then

begin

result := my_file.GetValue('COMPANY').ToString + ' - ' +

my_file.GetValue('FIRSTNAME').ToString;

MessageBox.Show('Customer found : '+result);

end

else

MessageBox.Show('Customer not found!');

end;

EasycomConnection Constructor

Creates a new instance of a EasycomConnection object, which represents an open connection to a specified AS/400.

Class EsycomConnection

Syntax

[Delphi] public constructor EasycomConnection();

[Delphi] public constructor EasycomConnection(connectionString:

String);

[Delphi] public constructor EasycomConnection(bdpCnx:

BdpConnection);

Description

Parameter Description Type

connectionString Specifies the connection string, including the necessary parameters to connect using Easycom. See EasycomConnection.ConnectionString property for options available in this connection string.

String

bdpCnx Specifies a Bdp connection object. If the connection ‘bdpCnx’ is not opened or not an Easycom kind connection type, an exception will occur.

You need to explicitly open and close connections using the Open and Close methods, respectively (except if the bdpCnx parameter was provided).

Because this connection can be "pooled", when you close the object (using .Dispose() or .Close() method) the physical connection may remain.

Example of use



result:string;

begin

my_cnx := EasycomConnection.Create('Server=194.206.160.111;User Id=

my_cnx.Open;

EasycomConnection.ConnectionString Property

Represents all options for the connection.

Class EasycomConnection

Syntax

[Delphi] public property ConnectionString: String read

get_ConnectionString write set_ConnectionString;

Description You set the ConnectionString property before opening a connection.

The option names are the same that the options available for EAConnection.ConnectionString, except for the username (User ID here instead of UserName for EAConnection.ConnectionString).

The available options are:

Server : The name or the IP address of the AS/400

User ID : The user profile. In interactive environment, if this parameter is omitted an Easycom dialog box will be shown. If this parameter is omitted in a service (for example in ASP.NET environment) an exception will be thrown during the connection.

Password : The password that belongs the username.

JobName : The job name to use. By default this is the name of the PC.

Pooled : Choose if pooling or not this connection object. See 'Pooling connection' topic for more details. Possible values are 'True' and 'False'. Default is True.

PoolLimit : Determines the limit of using pooled connection. When the limit is reached the thread will wait until a pooled connection is available or until the timeout is reached (see PoolTimeout parameter and 'Pooling connections' topic for more details). Non-pooled connections are not counted with this parameter. This value is an integer representing the maximum number of connections being pooled. Default is 0 (unlimited).

PoolTimeout : Represents the maximum number of seconds to wait if the pool limit is reached. Default is 0 (unlimited).

Shared : Choose if sharing the connection for the same thread. Possible values are 'True' and 'False'. Default is False.

Init Libl : Some libraries to add to the default library list (that belong to the user ID). This is a semicolon-separated list, like "MYLIB1;MYLIB2".

EacUnLock : A special password that can be validated by a user-defined AS/400 program. This avoids to non-authorised developers to use Easycom. See 'Advanced security features' in the server documentation.

CodepageFile : designates an ASCII-EBCDIC translation file. This is mostly useful for DBCS countries like China, Japan, Korea.

ShortFieldName : tells Easycom to use only short forms for field names. This will ignore aliases of columns. Valid values are 'True' and 'False'. Default is False.

SqlNaming : Choose between '.' and '/' to separate files and libraries. When using '.' the library list is not available (and current library is the name of the user). Possible values are '/' and '.'. Default is '/'.

EasycomConnection.Open Method

Opens the connection.


Syntax

[Delphi] public procedure Open;

Description

Call this method to open the connection. If the connections are pooled, this may only reuse an available connection.

If the EasycomConnection.ConnectionString is empty, the connection will open with all default values, and show the Easycom dialog box for the user and password (If being in service mode, like ASP.NET, an exception will be thrown with wrong user or password).

A connection is always materialized by a JOB on the AS/400. The Easycom jobs are running by default in the Easycom subsystem. Those jobs can visualized using the WRKACTJOB SBS(EASYCOM) command on a AS/400 terminal emulation (5250).

However, a single job can correspond to several EasycomConnection objects, depending on the EasycomConnection.ConnectionString parameters.

EasycomConnection.OpenFile Method

Opens a file.


Syntax

[Delphi] public function OpenFile(FileName: String):

EasycomFile;

[Delphi] public function OpenFile(FileName: String; openMode:

openFileAccess):EasycomFile;

[Delphi] public function OpenFile(FileName: String; openMode:

openFileAccess; bCommit: Boolean):EasycomFile;

Description

Opens a physical or logical file on the server this file can be natively used (ReadKey, ReadFirst, ...).


FileName Specifies the name of the file to open. This filename must specify a name, and can specify a library and/or a member.

String

openMode Specifies the open mode openFileAccess

(ReadOnly, ReadWrite, ExclusiveRead or ExclusiveReadWrite)

bCommit If true, the file will be opened in journaled mode, and will take part of transactions.

Boolean

The filename can have the following forms :

LIBRARY/FILE : the file is defined in an absolute form.

FILE : the file will be opened using the *LIBL (library list) rules.

LIBRARY/FILE(MEMBER) : the file is defined in an absolute form, with a specific

member (allows multi-member capable programs).

FILE(MEMBER) : opens a file using the *LIBL rules, with a specific member.

*PGM/PGM_DEF : opens an Easycom-defined program description. Allows native program calls (using key search function).

If the member is not specified the default member is opened. If a file has no member the function will fail.

This function returns an instance to EasycomFile class which is designed to allow

native actions possible to a file, including :

key access

direct update/insert/delete

record locking

native information on fields (column

heading, AS/400 data type, lengths,

etc.)

saving/retrieving position (using

Relative Record Numbers)

Remarks :

the LIBRARY can be QTEMP. But be

careful: QTEMP is a “memory” library valid only for the current JOB

the file opening process will follow file

substitutions that are performed on the job scope (OVRSCOPE(*JOB)

parameter of OVRDBF AS/400 command).

See also

EasycomFile constructor

EasycomConnection.RemoteCommand Method

Executes a native command.


Syntax

[Delphi] public procedure RemoteCommand(strCommand: String);

Description

EasycomConnection.RemoteCommand executes a command for the current connection.

This command can affect the environment (JOB) of the current connection. For example a command can run a program that will change the library list, the objects overrides,

and so on.

An exception (EasycomException) will be thrown if the command failed (command

syntax, or execution failure …).

The command syntax is like AS/400 terminal command line (best is to test the

command syntax in the terminal before using it in the method).

Restrictions: this method cannot call interactive commands (like DSPMSG). This method

cannot call commands that require return variables: use the RemoteRtvCommand

instead.

Example of use


result:string;

begin


my_cnx.Open;

my_cnx.RemoteCommand('ADDLIBLE MYLIB');

my_cnx.RemoteCommand('CHGDTAARA DTAARA(*LDA (1 2)) VALUE(AA)');

end;

EasycomConnection.RemoteRtvCommand Method

Executes a native command that returns variables.


Syntax

[Delphi] public procedure RemoteRtvCommand(strCommand: String);

Description

EasycomConnection.RemoteRtvCommand executes a command for the current

connection, with capability to have return values for parameters of the command. The command syntax is similar to CL language.

This command can affect the environment (JOB) of the current connection, or retrieve

some values depending on the job or the system.

The strCommand syntax is like a regular CL syntax, with & as variables prefixes. For

example:

RTVJOBA USER(&USR)

If a variable as a length superior to 20 characters or if a variable is not character type,

you need to declare it with CHAR(len) orDEC(len dec). All declarations are semicolon-separated. For example:

LIBL=CHAR(2750);DFTWAIT=DEC(7 0);RTVJOBA USRLIBL(&LIBL)

Subsequent calls of EasycomConnection.RemoteRtvCommandGetValue function is used

to get the returned variables.

An exception (EasycomException) will be thrown if the command syntax was incorrect.

However an exception is not thrown upon failure (as opposed to the

EasycomConnection.RemoteCommand method).

If the command syntax was correct, but the execution failed, a special variable name

“RC” will contain the CPF code of the error (no exception thrown). So a typical use of

this method will execute the command, test the “RC” variable, and finally get the other variable(s).

Remark: best is to use the RemoteCommand method if the command is not returning

values (better performance, and better error handling).

Example of use


result:string;

begin


my_cnx.Open;

my_cnx.RemoteRtvCommand('LIBL=CHAR(2750);DFTWAIT=DEC(7 0);RTVJOBA

USRLIBL(&LIBL)');

if my_cnx.RemoteRtvCommandGetValue('RC') = '0' then

begin

MessageBox.Show('User Library List: ' +my_cnx.RemoteRtvCommandGetValue('LIBL'));

MessageBox.Show('User Default Wait: '

+my_cnx.RemoteRtvCommandGetValue('DFTWAIT'));

end

else

MessageBox.Show('The command call returned the following

message'+my_cnx.RemoteRtvCommandGetValue('RC'));

EasycomConnection.RemoteRtvCommandGetValue Method

Gets a result variable for the last call of RemoteRtvCommand call.


Syntax

[Delphi] public function RemoteRtvCommandGetValue(strVariable:

String): String;

Description

EasycomConnection.RemoteRtvCommandGetValue gets a result variable for the last call of RemoteRtvCommand call.

A program should always get the “RC” variable before getting other variable(s).

The return type is always string not depending on the datatype of the host variable. However if the datatype of the return variable is decimal, it must be declared in the RemoteRtvCommand string.

See EasycomConnection.RemoteRtvCommand for more details.

EasycomDataSet

EasycomDataSet Class

Namespace Easycom

Syntax

[Delphi] type EasycomDataSet = class (System.Object);

Description

The EasycomDataSet class is the lowest-level class that handles basic operation on an opened file.

Those basic operations are: navigation (first, next, last, previous), getting data (by fieldname or by index), saving and restoring position, querying information on key or fields.

EasycomDataSet.GetFieldCount Method

Returns the number of fields in the dataset.

Class EasycomDataSet

Syntax [Delphi] public function GetFieldCount:Integer;

Description

This function returns the total number of fields in the dataset.

See also

EasycomDataSet.GetFieldInformation

EasycomDataSet.GetFieldInformation Method

Returns information on a specified field.


Syntax [Delphi] public function GetFieldInformation(f: Integer;

fieldInformation info):System.Object;

[Delphi] public function GetFieldInformation(fldName: String;

fieldInformation info):System.Object;

Description

This function returns the requested information as an object, which type depends on

the information being requested.

fieldInformation Type Comments

FieldName String The field name, short or long

(10 or 30).

EasycomType EasycomType The native datatype

Digits Short Total number of digits

Decimals Short Number of decimals

ServerLen Short Field size, in bytes

ColumnHeader String The AS/400 column header, 60 chars.

ColumnText String The AS/400 column text, 50

chars

Nullallowed Boolean True if the field can be null

See also

EasycomDataSet.GetFormatInformation

EasycomDataSet.GetFormatInformation Method

Returns information on the opened dataset.


Syntax [Delphi] public function GetFormatInformation(formatInformation

info):System.Object;

Description

This function returns the requested information as an object, which type depends on

the information being requested.

formatInformation Type Comments

fieldCount Int The total number of fields

fldKeyCount Short The number of fields in the key

keyUnique Boolean True if the key is unique

keySelOmit Boolean True if the key has a select or

omit clause

See also

EasycomDataSet.GetFieldInformation

EasycomDataSet.GetPosition Method

Gets the current position in the dataset.


Syntax

[Delphi] public function GetPosition: Integer;

Description

EasycomDataSet.GetPosition returns the current position.

If the dataset belongs to a file the position is a unique integer that is actually the

AS/400 relative record number, which as no relationship with the record rank.

If the dataset is a query, the position is a value relative to the first or to the last record.

The value is positive if the position is relative to the first record (for example = 4 if this is the 4th record), and negative if the position is relative to the last record (for example

= -4 if this is the 4th record starting from last).

If there is no current position, and exception will be thrown (will occur if the position is asked just after having opened a file).

Example of use

The following example gets the position of the last record (that is not the rank of the

last record).



result:string;

posi:integer;

begin


my_cnx.Open;

my_file := my_cnx.OpenFile('S_CUSTOMER');

if my_file.ReadLast then

posi := my_file.GetPosition();

end;

EasycomDataSet.GetValue Method

Get field values.


Syntax [Delphi] public function GetValue(f: integer):System.Object;

[Delphi] public function GetValue(flfName:

string):System.Object;

Description

These functions return the field value as an object. The object will be the nearest object

type that corresponds to the database type of the field.

The Object can be a String, Integer, SmallInt, …

The value can be obtained from the field name of from the field index (zero-based).

The field name is the alias name of the field if existing, except if short field names are forced using the connection string options.

Example of use

The following example reads the first record and gets field values.

var fic:EasycomFile;

cnx:EasycomConnection;

begin

cnx := EasycomConnection.Create(BdpConnection1);

fic := cnx.OpenFile('S_CUSTOMER');

fic.ReadFirst;

MessageBox.Show('Customer ID: ' + fic.GetValue('CUST_ID').ToString);

MessageBox.Show('Customer Name: ' + fic.GetValue('FIRSTNAME').ToString);

end;

See also

EasycomDataSet.ReadFirst

EasycomDataSet.ReadNext

EasycomDataSet.IsDBNull

EasycomDataSet.GotoPosition Method

Sets the current position in the dataset.


Syntax

[Delphi] public procedure GotoPosition(pos: Integer);

Description

EasycomDataSet.GotoPosition reads the record à the given position.

If the dataset belongs to a file the position is a unique integer that is actually the

AS/400 relative record number, which as no relationship with the record rank.

If the dataset is a query, the position is a value relative to the first or to the last record.

The value is positive if the position is relative to the first record (for example = 4 if this is the 4th record), and negative if the position is relative to the last record (for example

= -4 if this is the 4th record starting from last).

If the is an EasycomFile object, the fetched record may be locked or not depending on

the current fetch mode. The fetch mode is sequential read with no lock by default, and

can be changed using the EasycomFile.SetFetchmode method.

If the position is unreachable an exception will be thrown.

See also

EasycomDataSet.GetPosition

EasycomDataSet.GetValue

EasycomFile.SetFetchmode

EasycomDataSet.IsDBNull Method

Tests null value state of a field.


Syntax [Delphi] public function IsDBNull(f: integer):boolean;

Description

This function returns true if the field value is null.

See also

EasycomDataSet.ReadFirst

EasycomDataSet.ReadNext


EasycomDataSet.Readxxx Methods

Reads a record


Syntax [Delphi] public function ReadFirst:Boolean;

[Delphi] public function ReadNext:Boolean;

[Delphi] public function ReadPrev:Boolean;

[Delphi] public function ReadLast:Boolean;

Description

These functions are reading a record using the given direction. The function returns

true if a record is fetched and false otherwise.

If the is an EasycomFile object, the fetched record may be locked or not depending on the current fetch mode. The fetch mode is sequential read with no lock by default, and

can be changed using the EasycomFile.SetFetchmode method.

The field values for the current record can be accessed using the GetValue function.

Example of use

The following example reads the first record and gets field values.



begin


fic := cnx.OpenFile('S_CUSTOMER');

fic.ReadFirst;



end;

See also


EasycomFile.SetFetchmode

EasycomFile

EasycomFile Class

Namespace Easycom

Syntax

[Delphi] type EasycomFile = class (EasycomDataSet);

Description

The EasycomFile ia a class that handles all possible native operations on an AS/400 file.

Basic operations are available on the parent class “EasycomDataSet”.

File specific operations are available on this class, including record-locking, insert,

update, delete, key seek.

EasycomFile Constructor

Creates a new instance of a EasycomFile object, which represents an opened file in an AS/400 connection.

Class EasycomFile

Syntax

[Delphi] public constructor EasycomFile(cnx: EasycomConnection;

FileName: String);


FileName: String; openMode: openFileAccess);


FileName: String; openMode: openFileAccess; bCommit: Boolean);

Description


Cnx Specifies the connection object to which the file opening will belong to

Easycomconnction

FileName Specifies the name of the file to open. This filename must specify a name, and can specify a library and/or a member.

String

openMode Specifies the open mode (ReadOnly, ReadWrite, ExclusiveRead or ExclusiveReadWrite)

openFileAccess

bCommit If true, the file will be opened in journaled mode, and will take part of transactions.

Boolean

The filename can have the following forms:

LIBRARY/FILE : the file is defined in an absolute form.

FILE : the file will be opened using the *LIBL (library list) rules.

LIBRARY/FILE(MEMBER) : the file is defined in an absolute form, with a specific member (allows multi-member capable programs).

FILE(MEMBER) : opens a file using the *LIBL rules, with a specific member.

*PGM/PGM_DEF: opens an Easycom-defined program description. Allows native program calls (using key search function).

EasycomFile.ReadKey Method

Seeks a record with key values

Class EasycomFile

Syntax [Delphi] public function ReadKey(keyValues: object):boolean;

[Delphi] public function ReadKey(keyValues: object;

lastFieldPartialLen: integer):boolean;


op:keyReadOp):boolean;


op:keyReadOp; lastFieldPartialLen: integer):boolean;

Description

These functions seek a record using the specified values for the key. The function

returns true if the record was found and false otherwise.


keyValues Specifies the key values. If there is only one key field or if the seek must be done only on the first field, the value can be a simple CLR type (like string, integer, …). If several key values needs to be specified, the keyValues object must be an array of CLR types.

object

lastFieldPartialLen

Allows partial key search. This represents the length, in bytes, of the significant part for the last key value specified.

Integer

Op Specifies the key operation verb. The possible values are:

Eq : must be equal (totally or partially depending on other parameters).

Ge: must be greater or equal (>=

Le: must be less or equal (<=

Gt: must be strictly greater (>)

Lt: must be strictly less (<)

NextEq: must follow current record and be equal

PrevEq: must precede current record and be equal

keyReadOp

NextUnEq: must follow current record and be not equal

PrevUnEq: must precede current record and be not equal

This function allows real native usage of the key that is in the logical or physical file.

The application must open the correct logical file in order to use a specified key (then it is possible to use EasycomDataSet.GetPosition/EasycomDataSet.GotoPosition to

synchronise different logical files).

The “lastFieldPartialKeyLen” allows partial key search. If n key values are specified in

the keyValues parameters, “lastFieldPartialKeyLen” represents the size of the nth key

field. In other words, the key search will ignore the rest of the key.

If “lastFieldPartialKeyLen” is omitted the read will be performed on all key fields

specified (ignoring others).

Examples

Suppose that you have a logical file that has a key with Country ID has Packed Decimal

4 digits, and customer name. If you want to seek the first customer that begins with

“LA” string in a specified country, you will have a code like:



begin


fic := cnx.OpenFile('s_cust_cnfn');

fic.ReadKey(New(array[] of string, ('US', 'P')) , 1);



MessageBox.Show('Country: ' + fic.GetValue('COUNTRY').ToString);

end;

To seek the first “US” country:

fic.ReadKey(New(array[] of string, ('US')));

or:

fic.ReadKey('US');

To seek first customer beginning with “Jo”:

fic_cust = cnx.OpenFile('s_cust_na');

fic_cust.ReadKey('Jo', 2);

See also

EasycomDataSet.GetPosition

EasycomDataSet.GotoPosition

EasycomFile.RecordAppend Method

Puts the EasycomFile object into an append mode.

Class EasycomFile

Syntax [Delphi] public procedure RecordAppend(clear: Boolean);

[Delphi] public procedure RecordAppend;

Description

This function puts the EasycomFile object into append mode.

If clear is true (default), all fields will be cleared. Otherwise the field values of the

current record (or the last inserted record) will be used.

Subsequent calls to EasycomFile.SetValue must be performed to give field values.

A call to EasycomFile.RecordUpdate must be performed to validate the record

appending.

EasycomFile.RecordDelete Method

Deletes the current record.

Class EasycomFile

Syntax [Delphi] public procedure RecordDelete;

Description

This function deletes the current record. The record must have been locked before

(using the RecordLock method or using the Locked fetch mode).

EasycomFile.RecordLock Method

Locks the current record.

Class EasycomFile

Syntax [Delphi] public procedure RecordLock;

Description

This function locks the current record. If the fetch mode is “Locked”, this function as no

effect.

If the record has changed between the fetch (ReadKey, …) and the RecordLock

function call, an exception will be thrown.

When the record is locked, EasycomFile.RecordDelete and EasycomFile.RecordUpdate

are allowed.

EasycomFile.RecordUnLock Method

Unlocks the current record.

Class EasycomFile

Syntax [Delphi] public procedure RecordUnLock;

Description

This function unlocks the current record. If the fetch mode is “Locked”, this function

unlocks the current record, but will continue to lock records for future fetches.

EasycomFile.RecordUpdate Method

Validates record changes or record appending.

Class EasycomFile

Syntax [Delphi] public procedure RecordUpdate;

Description

This function validates record changes or record appending.

This function call is valid after a call of EasycomFile.Append, after a call of

EasycomFile.RecordLock or if a record is fetched in “Locked” fetch mode. In other

words, the object must be in append or in locked mode.

Previous calls of EasycomFile.SetValue must have been performed to set field values.

EasycomFile.SetFetchMode Method

Chooses a fetch mode depending on the EasycomFile object usage needed.

Class EasycomFile

Syntax [Delphi] public procedure SetFetchMode(mode: fetchMode);

Description

This function chooses a fetch mode. Possible values for mode are:

Locked: each fetch is locked. This fetches records only one by one, but always locked. This allows safe multiple updates.

Unlocked: standard native fetches. Limited cache size for optimum native access (key searches, …)

SequentialUnlocked (default): Unlocked, but with large cache size. Optimized for

Forward-only fetches.

EasycomFile.SetValue Method

Defines a field value for modifying or inserting a record.

Class EasycomFile

Syntax [Delphi] public procedure SetValue(f: integer; Value:

System.Object);

[Delphi] public procedure SetValue(fieldName: string; Value:

System.Object);

Description

This function changes a value for the specified field. This function call is valid only when

having the current record locked or when being in append mode.

Example 1

This example uses the implicit record locking. Lock error may occur when reading the record.



begin


fic := cnx.OpenFile('s_customer', openFileAccess.ReadWrite);

fic.SetFetchMode(fetchMode.Locked);

if fic.ReadKey(1354) then

begin

fic.SetValue('STATE', 'CA');

fic.SetValue('CITY', 'San Francisco');

fic.RecordUpdate;

end;

end;

Example 2

This example uses the explicit record locking. Lock error may occur when locking record, if lock fails or if the record changed between the “read” and the “lock”.



begin


fic := cnx.OpenFile('s_customer', openFileAccess.ReadWrite);

if fic.ReadKey(1354) then

begin

fic.RecordLock;

fic.SetValue('STATE', 'CA');

fic.SetValue('CITY', 'San Francisco');

fic.RecordUpdate;

end;

end;

EasycomException

EasycomException Class

The EasycomException class will be created by other classes methods when an Easycom error

occur. This can be trivial error like modifying a field value when no current record is locked, or

any failure message coming from the AS/400.

Message Property

Class EasycomException

Syntax

[Delphi] public property Message: String;

Description

This property is the default message, which will be shown to the user if the exception is

not caught by the program.

This property usually contains the error codes, the message and full message.

NativeCategory Property


Syntax

[Delphi] public property NativeCategory: EasycomNativeCategory;

Description

This property represents the category when having an Easycom kind exception.

The possible values are:

Error: general native error. This error is generally generated locally. This can be field name invalid, …

Signal: AS/400 classic error, like file not found, … With this category, the NativeMessage will contain the message AS/400 ID (CPF5715 for example) and NativeFullMessage the corresponding error message (File XX not found in *LIBL).

Sql: all Sql-level errors.

Tcpip: all TCP/IP errors.

Internal : Easycom internal error. This can be a licensing problem (see the message field for more details).

InternalInterface: Internal to the PC-side interface (the .NET core). This error category can denote a bug inside Easycom or an unexpected way of using the assembly.

NoError : no error was generated. This is the initial value if the EasycomException created with the empty constructor.

Unknown

ExceptKind Property


Syntax

[Delphi] public property ExceptKind: EasycomExceptionKind;

Description

This property represents the main exception level. Two values are possible:

Easycom: the exception was caught on the Easycom level (internal in Easycom, AS/400 message, …)

EasycomDotNet: the exception was caught inside the Easycom .NET assembly itself (wrong field number, …)

EasycomNativeErrorCode Property Represents the native error code. The value depends on the error kind and category. If the

category is Sql this is the sql error code. If the category is TCP/IP, this is the TCP/IP error code.

If the category is Signal, this is the AS/400 return code.

EasycomNativeFullMessage Property


Syntax

[Delphi] public property EasycomNativeFullMessage: String;

Description

This property is the full native message, if available. This message comes from the AS/400 messaging system if the exception was caused by an AS/400 message (‘file XX not found in *LIBL for example), or can be an Easycom internal message if this is a logic problem (like “Invalid FieldName”)

EasycomNativeMessage Property


Syntax

[Delphi] public property EasycomNativeMessage: String;

Description

This property is a short native message, if available. This message comes from the AS/400 messaging system if the exception was caused by an AS/400 message, or can be an Easycom internal message if this is a logic problem (like “Invalid FieldName”).

For example, if an AS/400 message is caught, the EasycomNativeMessage will contain the message ID (like CPF5715).

NB: This value is sometime the same as EasycomNativeFullMessage.

EasycomNativeReturnCode Property


Syntax

[Delphi] public property EasycomNativeReturnCode: Integer;

Description

Represents the native return code. This code is an Easycom-specific code.

The value can be one of the following :

2 Too many opened files

3 Not enough memory

4 Invalid pointer or Handle

5 File not found

6 Wrong key field number

10 File not allowed to be changed

13 Record locked

17 Operation sequence not valid

20 No current record

21 Null operation not applicable (field does not support null value)

24 Insufficient user rights

25 Invalid type provided

26 Info request is invalid

28 The record has changed before update

29 Already in a transaction (nested transactions are not supported)

30 Not in a transaction

22 AS/400 session ID not valid

16 Not connected

23 Wrong user or password

27 Bad property ID

12 The requested record was not found

8 Bad key length

11 The file was opened in a mode that disallows a file lock, or you have insufficient rights to perform operation

14 Begin or end of file has been reached

15 Read beyond limits of the file

6 Failed to find the field in the logical file

7 The field number is invalid

AS/400 Functions

Stored procedure configuration

AS/400 programs do not have any external description.

The program expects data in parameters, and returns results through the same parameters.

Only the program itself knows about the type and size of those parameters.

You need to describe your program, because Easycom For Delphi needs to know how to translate the information from AS/400 into PC format.

If your program has a variable structure depending on the value of a parameter during the CALL, you can provide multiple descriptions for the same program.

Each description will have its own procedure name.

The EASYCOM Stored Procedure Configuration tool allows you to describe any program on the AS/400 by giving the type and size of each parameter it expects to receive.

You can describe any AS/400 program written in any AS/400 language (RPG, COBOL, CL, C, etc.).

The only restriction is that the program must not do any screen or keyboard I/O, because it will be treated as a stored procedure, and will be an extension of the Easycom server.

Rpc - DTAQ Configuration tool

You can start the RPC/DTAQ Configuration tool from the shortcut in the program group “ACE400”.

See : Describing AS/400 native programs

Program description Start the « EASYCOM Stored Proc Configuration » , in the program group « ACE400 ».

2. Create a new procedure.

3. Complete the dialog box with the Procedure description :

Procedure Name : This name will be the only one used on the client side. Your

application will open and call this procedure name.

Description : Enter any text to describe your procedure.

AS/400 Program Name : The complete AS/400 qualified program name.

LIBRARY/PROGRAM

Program/DataQueue : Leave this Combo Box in Program state.

4. Describe the parameters expected by your program.

Because on AS/400, a parameter can be a Data Structure, you need to describe each Field (item of the Data Structure), and to put the type of the field (parameter or first field of a Data Structure or not).

You can Add, Delete or Modify field descriptions by clicking the "+", "-" or "M" buttons.

Complete the next Dialog box "Parameter field edition" :

Field Name : The field to be used.

Field usage : The field is sent to the program (IN), or it is the return result of the

program (OUT) or both. Usually the parameters are IN/OUT.

This field is a parameter or the first field of a Data Structure : This box must

be unchecked only if the field is in the second or greater position inside a parameter that is a Data Structure.

AS/400 format : Describe exactly which data format your program expects : Data

Type, Number of characters or digits for a decimal value, and the number of decimals.

PC format : Describe how you want the data to be converted by Easycom.

You can use this process to describe several programs, also you can provide multiple descriptions for the same program, if needed.

See StProc sample provided for a complete example.

DataQueues description

You can also create procedures for all type of known AS/400 Data Queues : simple file (FIFO) or keyed file (KEYED).

“DTAQ_FIFO” is an example based on simple dataqueue while “DTAQ_KEY” is an example with keyed procedure

1. Start the “ Easycom Stored Proc Configuration ” in the program group “ ACE400 ”.

2. In the “ Stored Procedure configuration ” window, select “ New Procedure ”.

3. Complete the dialog box "Procedure definition" :

Procedure Name : This name will be the only one used on the client side.

Description : Enter any text to describe your DataQueue,

AS/400 Progam Name : Path (<Library>/ <Program>) to the DataQueue,

Program/DataQueue : "DataQueue".

4. Describe the fields of your Data Queue. Using “ + ”, “ – ” or “ M ” buttons, you can

add, delete or modify fields.

In the description of the DataQueue format, you have to create three fields used by Advanced Client Easycom/400 for Delphi.

TIMEOUT : ‘char’ type , size 6 Time-out reading delay,

FILER : ‘char’ type , size 2 Future use,

ORDER : ‘char’ type, size 4 Kind of key operation (DataQueue KEYED),

In case of Keyed Data Queue, fourth field is the key

Complete the next Dialog box "Parameter field edition" :

Field Name : Virtual name of the field,

Field usage : No meaning for the DataQueue.

This field is a parameter or the 1st

of a Data Structure : No meaning for the

DataQueue,

AS/400 format : Describe exactly which data format your program expects : Data

Type, Number of characters or digits for a decimal value, and the number of decimals,

PC format : Describe how you want the data to be converted by Easycom.

You can use this process to describe several Data Queues, and you can provide multiple descriptions for the same Data Queue, if needed.

Examples

Running the Sample Programs

Some sample Delphi programs have been installed in your ACE400\SAMPLES sub-directory.

These samples demonstrate some of Easycom For Delphi's features and capabilities.

Please note that some samples are 32-bits only.

Delphi\MasDetTb\ (32 bit)

In this sample we are given a chance to look at two tables in a database.

When you start the program it will look like below :

The top look-up is for choosing the master table.

The bottom is for choosing the detail table.

The grids will show the respective tables.

For now we shall choose SP_CUST for the master table, and SP_ORD for the detail table.

Once you have choosen the tables click on Link. The following form should appear:

The lists show the fields in the two tables. Left being the master table and the right being the detail table.

Click on the field that is common between the two, CUST_ID.

Click on Add. The grid on the bottom shows the fields relationship.

Click on OK.

What you now shall see is that the detail grid will only show those fields that pertain to the customer that the master field is pointing to.

Delphi\MasDetTQ\ (32-bit)

The second sample shows you the compatibility between Easycom For Delphi and the TQuery component.

The query syntax submited has to comply with AS/400 Query syntax requirements.

ACE/400 submits the supplied Query to the AS/400 query engine to be performed.

So, If you intend to make extensive use of TQuery, you should consider using Easycom For Delphi.

The second sample shows you the compatibility between EASYCOM Idapi Driver and the TQuery component.

Even if this is not the fastest way to access the AS/400 (because in this case the SQL engine of the AS/400 which wraps the Physical/Logical files layout will be activated on the AS/400), it is good to know you have a complete compatibility with the TQuery component.

Running this example as is will give you DBEdits and a grid show the prevelant information.

Similar to the MasterSettb sample, we see the master table, customer information, and the detail table, the order information, and their relationship through CUST_ID.

This sample does allow for editing, adding, and deleting of records. Try it.

The MastDetTQ sample was created using the Delphi Master/Detail Form Expert, using a TQuery.

It uses SP_CUST and SP_ORD, the CUST_ID field as MasterKey, but no Logical Files on the AS/400, which accounts for the slower performance.

Delphi\LookUp\ (32-bit)

This sample shows you the compatibility between Easycom For Delphi and DBLookUpListBox and DBLookUpComboBox.

It is based on two files with logical files.

Again, we are showing a master-detain relationship. The master table is SP_CUST giving all the customer information. The detail table happens to be SP_STATE, which gives the state name to state code. You travel through the records using the navigator. What the lookupbox and lookupcombo allows you to do is change the state in the SP_CUST table. Inserting and deleting records is also poosble in this sample.

Delphi\FlyIndex\ (32-bit)

The FlyIndex sample demonstrates how to use logical files as indexes, as well as a direct call to the AS/400 database system through the API in order to create temporary indexes on the fly.

This sample uses SP_CUST to show the table in acsending order by whatever choice the user wants. The user might choose an already existing field or describe is own.

Delphi\Filters (32-bit)

The Filters sample demonstrates how to do on the fly filtering of a TTable.

It uses standard Delphi properties and methods and allows you to change the filter applied to a table on the fly.

Filtering in this sample is based on both a range of values for sales and a country code.

This particlar sample only takes to tables and a button to filter the files. What helps is the following code : Table1.Filtered := False ; Table1.Filter := 'SALES>=' + SalesMin.Text + ' AND SALES<=' Table1.Filter := Table1.Filter + ' AND COUNTRY=' + '''' + DBLookUpComboBox1.KeyValue + ''''; Table1.Filtered := True ; This tells the program to filter Table1 and how to filter it.

Delphi\Find (32 bit)

The Find Sample uses the Find methods on a key field.

You can find a value in the FIRSTNAME field or a nearest value.

You can also search a null Value.

This is from a Table in Easycom called People. The buttons are user-defined that call on pre-existing procedures. Find Key uses the FindKey procedure, which looks for an exact match. Find Nearest calls on FindNearest, which looks for the closest match. Find Null calls on FindKey passing the NULL character as a parameter.

Delphi\StProc (32 bit)

This sample demonstrates the Remote Procedure Call capabilities of Easycom For Delphi.

The AS/400 CL program takes 5 parameters.

3 of them are packed decimal, the others are strings.

The result should be the addition of parms 1 & 3 in parm3, and their multiplication in parm5.

The strings is copied from parm 2 to parm 4.

The remote procedure call capability is present inside the StoredProc Delphi component.

The parameters have been described using an external program called “RPC configuration” (the description of stored procedures are stored on the AS/400).

The single button makes a “ExecProc” on the procedure (and a “prepare” for the first time)

Delphi\DCube (32 bit, Delphi 3-7 only)

This sample is based on Decision Query. You can see a Decision Grid and a Decision Graph.

Running the sample will give you the following screen :

Click on Open to start the sample.

The decision grid show the table the graph is based off of.

The buttons on the botom : YEARM, REGION, and COUNTRY, allow you to choose which fields you want to influence the graph.

To change the database you want to view, go into Delphi, and open the sample. Open the form and right click on the Decision Query. Select the Decision Query Editor.

This will bring up the following form:

From here, you can choose the Database, Table, which fields to use, the sums of fields, or customize it personally.

This query builds the following lines automatically:

SELECT COUNTRY, YEARMONTH, REGION, SUM( SALES ) ssum

FROM SLS_SREG

GROUP BY COUNTRY, YEARMONTH, REGION

Delphi\Bench

This sample’s main purpose is to check the size of a table, the number of records, and how long it takes to transverse those records. It was also designed to create files to run tests on.

The aliases on top refers to database names. Sample file name determines which table the program will look into. In this sample, we went with Bigfile.

The benchmark has two buttons, Sequential and Random I/O. Sequentil refers to starting from the beginning and going in order to the end. Random refers to randomly picking the records. Number of Iterations determines how many of the records will be read. The ReadOnly check refers to whether you want to add, delete, or edit the records.

Under the File Creation, there are the Create file and Fill Data buttons.

They create a test file and the fill it full of data.

The first Record number is the index number the table will start at. The last Record number is the last index number.

There is also a record of how long it takes to transverse the records. This tells you the starting time, finish time, total time to transverse the records, average time per record, and the total number of records.

Also are two buttons that either turns the grid on or off.

To run it, choose your database.

Either choose a table to test, or make your own. You can transverse the records using squential or random I/O. Try both, see if there is a time difference between the two.

Don’t forget, you can edit the records as you go along.

Advanced Security Features with TCP/IP

Advanced Security Features with TCP/IP

By default the EASYCOM Job is launched by the daemon program EASYCOMD running in the EASYCOM subsystem.

EASYCOMD searches for a program named EACTCP003 that allows to customize connection check. This program EACTCP003 can be in the library list or in the Easycom library.

So, it is possible to customize security by simply creating a EACTCP003 program.

EACTCP003 program interface (CL)

PGM

PARM(&TPPGM &TPLIB &USER &EAC_PARM1 + &EAC_PARM2 &RMT_ADR &JOBNAME)

DCL VAR(&TPPGM) TYPE(*CHAR) LEN(10) DCL VAR(&TPLIB) TYPE(*CHAR) LEN(10) DCL VAR(&USER) TYPE(*CHAR) LEN(10) DCL VAR(&EAC_PARM1) TYPE(*CHAR) LEN(30) DCL VAR(&EAC_PARM2) TYPE(*CHAR) LEN(30) DCL VAR(&RMT_ADR) TYPE(*CHAR) LEN(50) DCL VAR(&JOBNAME) TYPE(*CHAR) LEN(10)

Short description of each parameter

TPPGM : Target Program Name

Name for the server program that will be launched. Default is Easycom.

TPLIB : Library where TPPGM is

Location of the server program.

USER : User Name

User Name for the new connecting client (can be used to allow only a set of users)

EAC_PARM1 : Parm 1 to send to the TPPGM

Parameter to give if you make the SBMJOB yourself.

EAC_PARM2 : Parm 2 to send to the TPPGM

Parameter to give if you make the SBMJOB yourself.

RMT_ADR : TCP/IP adrress of the caller

TCP/IP Address of the caller (can be used to allow only a set of workstations)

JOBNAME : Job Name for the SBMJOB

Name for the job that will be in the Easycom subsystem. Default is workstation name.

If this JOBNAME is changed to *NO, the EASYCOM job will not be started.

If this JOBNAME is changed to *YES, the EASYCOM job will be accepted, but not the EASYCOM job is supposed to be started by EACTCP003 program.

Example

EACTCP003 can check the authorization of the user and his TCP/IP address, and then it can do one of the following:

Give authorization to run:

EACTCP003 leaves the variable &JOBNAME as it is, or change it to another job name, and then exit normally.

EASYCOMD will launch the target program with this new name.

Denny the execution:

EACTCP003 changes the value of &JOBNAME to ‘*NO’, and then exit normally. CHGVAR VAR(&JOBNAME) VALUE('*NO')

Launch itself the target program:

EACTCP003 launches the target program by a SBMJOB and changes the value of &JOBNAME to ‘*YES’.

CHGVAR VAR(&JOBNAME) VALUE('*YES')

SBMJOB CMD ( CALL PGM(&TPLIB/&TPPGM)+ PARM (&EAC_PARM1&EAC_PARM2))

JOBD(&TPLIB/EACJOBD) + USER(&USER) RTGDTA(*JOBD)

Common Problems

Common Delphi problems

The Delphi16/VCL directory must be in your path, if you exceed the path limit you'll need to

map a drive or consolidate VCLs in a separate directory to ensure they are all found.

Using Language Conversion Tables

In some countries (i.e. Israel), you would need to use translation table. This is the case when the AS/400 or the PC does not produce US/LATIN EBCDIC or ANSI characters. This will allow Delphi DataAware controls to work properly.

To use the conversion table, modify the “CODEPAGE FILE” in the alias configuration as follow :

CODEPAGEFILE …MyDirectory\MyPath\MyConversionTableName

Easycom For Delphi comes with a set of conversion tables. They all follow the naming convention :

Table name convention :

EnnnAmmm.tbl

Where

nnn is the EBCDIC code page.

mmm is Ascii code page. Ammm can be replaced by ANSI.

Ex : C:\ACE400\CodePage\e297ansi.cpg

The contain of a table is :

Bytes 0 to 255 = EBCDIC to ASCII Conversion.

Bytes 256 to 511 = ASCII to EBCDIC Conversion.

The value of the character will be used as an index in the table.

Example:

To translate character '0':

'0' = 0xF0 (240) in EBCDIC

'0' = 0x30 (48) in ASCII

Offset 240 of the file contains value 48.

Offset 560 (512+48) contains value 240.

If the alias is modified in such a way that the translation may not generate an ANSI character set. So, the 'Langdriver' in the alias may have to be set properly, using Borland's tables (use BDE administrator). Langdriver is commonly set to “‘ascii’ ANSI”.

As an example, use the table ExxxAyyy.TBL. If your PC is using a Windows code page yyy and your AS/400 is using an EBCDIC code page xxx.

In such a case you will need to set the 'LangDriver' accordingly.

Known Limitations

Using the Database Desktop to access AS/400 table will result in an error.

This is due to an undocumented IDAPI function called by the Database Desktop and we don't expect this to be resolved in a future release.

Note that it does not make any sense to modify the structures of the AS/400 table using the Database Desktop instead of the AS/400 native tools as most of the AS/400 tables features are not directly mapped to PC equivalent.

TBatchMove has been successfully tested in a lot of situations (see MoveFile sample).

However, if the file already exists in the AS/400 you will get an execution error.

This is not the standard behavior of the TbatchMove component as it should override the existing table, however it is a pretty safe protection against wrong manipulations.

FAQ

Installation FAQ

With TCP/IP, installation claims `Connection refused' TCP/IP installation is using the FTP protocol. This error means that no FTP server is running

on the AS/400. You can start the FTP server using the command ‘STRTCPSVR

SERVER(*FTP)’.

My alias and drivers were not created by setup Before running the installation, all Delphi or other IDAPI applications must be shut down. Try to

close all your applications and re-execute the setup.

Limits FAQ

Is Easycom compatible with MIDAS ?

Yes.

Is Easycom multithread compliant ? Yes, but it is guaranteed with native TCP/IP connection only (because many routers are not

thread-safe). Please consult manual to know how to configure it.

What is the limit of the number of fields in an index ? Unfortunately, Borland IDAPI has a limit of 16 fields for an index. Some AS/400 files can have

more. With Easycom For Delphi this index will appear like a regular index but with only the 16

first fields.

Common Problems FAQ

My Index list is not complete, or was not updated from recent changes !

The index list will only contain 'true' indexes, so all logicals will be shown except special logicals like :

- multiformat logicals.

- logicals with select/omit clauses.

To use these logicals, use the 'TableName' property of your TTable component.

Easycom maintain a cache of the index list, because the BDE often asks for this index list. This improve the time for opening a file during runtime. At runtime or with deployment, this cache is never cleared or updated.

So, to have the correct list, ask for your Index list within Delphi or C++ Builder. The index list will be updated in these situations :

- with a TTable component WHEN ACTIVE is FALSE.

- with Database Explorer UNDER DELPHI (opened with the Database/Explore menu).

If you are still having problems, you can clear EASYCOM index list cache. It can be done executing 'DELETE FROM EASYCOM/YIDXR0100' from the database explorer (where EASYCOM is the AS/400 library that contains the Easycom server).

My application is too slow, how to tune it up ?

Here are some rules that can help to speed up an Easycom application :

1. TTable <-> TQuery

TTable is faster because it uses Record-level accesses. It uses the key fields in native mode.

So TQuery should only be used when TTable usage is impossible. You even can create additional logicals (with select/omit for example) to avoid Tquery.

TQuery and TTable are allways faster when used in Read/Only mode. So if you don't need to update your data, always select the Readonly mode to your components (ReadOnly:=true for TTable, and Requestlive:=false for TQuery).

2. Setrange <-> Filters <-> OnFilterRecord

This is important to know how these different filtering features are working :

- SetRange is a record-level action (it relay on Key fields defined in IndexFieldNames).

- Filter generates an OPNQRYF each time the filter expression is changed.

- OnFilterRecord is a local filtering. It means that all records will be read.

So, always prefer a SetRange (or SetRangeStart ...) to filters.

The filter is powerful when you only have to filter with always the same expression. But if you want to change often the filter expression it can be a little bit slow. It also can be slow if you often deactivate/activate the filter.

How to solve this situation ?

You can combine a SetRange with an OnFilterRecord. The setrange clause will eliminate most records, and OnFilterRecord will only eliminate some others.

Of course in some cases, filter property will be very useful. Just be careful to not have a filter on each TTable component !

3. DBLookupComboBox

To tune your DBLookupComboBox, be careful to have a keyField for the ListSource that is the keyfield in your TTable. If your list source is a 'Detail TTable', best is to have a key that involves the masterfields and the key of your list source.

Example :

You have 3 files :

- COMPANY (COMP_ID, COMP_NAME, ...)

- PEOPLE ( COMP_ID, PEOPL_ID, PEOPL_NAME, ...)

- COUNTRY ( COUNT_ID, COUNT_NAME, ...)

Imagine you want to have a DBLookUpCombo for choosing somebody (POEPLE file) of the COMPANY, and another to choose a COUNTRY. Of course COMPANY is a MasterSource of PEOPLE on the COMP_ID field.

You will have best results if you choose the correct IndexFieldNames for PEOPLE and COUNTRY files :

PEOPLE : COMP_ID;PEOPL_ID

COUNTRY : COUNT_ID

However, just select PEOPL_ID in the DblookupComboBox component.

So COMP_ID will be used for the Master/Detail relationship (as a partial key), and PEOPL_ID will be used for the DBLoopUpCombo.

NB : if you don't select the right IndexFieldNames (for example COMP_ID instead of COMP_ID;PEOPL_ID), Delphi will generate filters to mach the record, and it will be more slow (the result will be the same, but slower).

Decision cube omits sometimes some columns. How to fix that ?

Decision cube components generates an SQL query.

You can see it by clicking on 'SQL' property of your TDecisionCube component.

This query often like :

SELECT x, y, SUM(z)

GROUP BY x, y

And the Decision cube component will assume that x and y values will come in the right order.

But the AS/400 SQL engine never sorts the result if you don't ask it so.

So, to be sure to have correct results, just modidy the SQL query like this :

SELECT x, y, SUM(z)

GROUP BY x, y

ORDER BY x, y

AS/400 specifics FAQ

How to execute AS/400 commands ?

Use the Easycom For Delphi special component ‘ACE400RCmd’.

How to call AS/400 programs ?

Use the TstoredProc component to call programs with input/output parameters. The procedure

must be created before using the PC program ‘EASYCOM Stored Procedures configuration’.

Please see our manual for more details.

How to access Data queues ? Dataqueue access is also very easy to use (for data queues with and without key). This is done

by using regular Ttable components !

How to have the source of the AS/400 files made by EASYCOM ?

When using CreateTable, TBatchmove, or the Datapump tool, EASYCOM creates AS/400 files.

You might want to change the file descriptions.

With EASYCOM, files can be created with DDS or with SQL.

1. When creating table using DDS

DDS is used if the AS/400 file name fit 10 characters and CRTTABLE SCRIPT setting of CONVERSION RULES is not used.

The DDS source is created in QDDSSRC in the library you created the file.

You will have the original field name in COLHDG if it is longer than 10 characters.

You will also have the ALIAS clause to have long names with your DDS.

All fields will be null capable by detault.

So you can change the source, and simply recompile it !

2. When creating table using SQL

SQL is used when file names are longer that 10 characters (AS/400 long file names) or when CRTTABLE SCRIPT option in CONVERSION RULES option is used.

You can have the SQL statements generated in a PC file.

Change CONVERSION RULES like this:

CONVERSION RULES=CRTTABLE SCRIPT=

You will have all the SQL table creation statements generated in that file. You will just have to transfer it to your AS/400 and use RUNSQLSTM to execute it after modifications.

This file will also contain the index creation statements.

How to access join files ?

Join files are used like regular files. Simply fill TableName with the name of the join file.

How to make a case insensitive key search or use a different sort display ?

For each AS/400 logical/physical, you can define a sorting sequence (diffrent from the current sorting sequence).

Check the QSRTSEQ system value to see what is your system's default value. You also can check your job attributes (with option 2 of dspjob). The dedault system's value is *HEX.

To provide a case insensitive key search, you can create a logical file with ALTSEQ option, giving a file like QSYS/QSYSTRNTBL. Use ‘go CMDTBL’ to display, create or modify the tables.

How to make Delayed updates working ?

Delayed updates cannot work with AS/400. The AS/400 does not permit multiple locks on a file,

and Delphi tries to do this. So, it is not advisable to use Delayed updates.

How to access file members ?

For a file (using Ttable), simply use syntax LIBRARY/FILE(MEMBER) in the TableName property.

For queries, use OVRDBF AS/400 command to select the member.

How to use 36 files ?

If you don’t have any description created on the AS/400, create and empty Physical file in

AS/400 mode (DDS) that has the description of the F36 record. Then fill-up the ‘TableName’

property as follows :

How to call an interactive program from Easycom For Delphi ? It is not possible to do this directly. But it is possible to call a non-interactive program and

communicate with it using a Dataqueue.

How to call a Delphi program from an AS/400 menu ?

This can be done with our product Launcher/400.

See our web site http://www.easycom-aura.com

Is it possible to retrieve jobs properties such as user profile, user library list, and so

This is easily done with the component ‘ACE400Rrtv’. This components allows to easily use

‘RTV’ commands like RTVJOBA or RTVSYSVAL. Install the components and try the sample

‘Delphi\RCmd’.

Is it possible to work with multiple AS/400 at a time and how ?

Simply create multiple Tdatabase components or multiple aliases and use them.

Does the product support journalized files and how? With Easycom For Delphi it is used exactly the same way it is with any SQL database (using

Tdatabase components methods).

Does Easycom For Delphi Support files with Select/Omit ? This is fully supported. But because of not being true indexes they do not appear in the

‘IndexName’ property of a Ttable Component. As they are not true indexes, this is safe to use it

like a physical file (referencing it in the ‘TableName’ property).

EASYCOM Server

Introduction to the AS/400

Introduction to the AS/400

The AS/400 is a computer designed and built by IBM. Its date of birth could be said to be the 8 January 1970 (Operating System/400, OS/400) in Rochester, Minnesota.

The AS/400 operating system is OS/400, and in particular this contains :

RPG : Compiler : RPG/400

CL : Command language for the AS/400

IRP : Intermediate Representation of a Program

MI : Made up of two components : instructions and objects.

Libraries

A library is an OS/400 system object containing other objects. Its organization is based on a single hierarchical level, unlike the directory structures on microcomputers and under the Windows and Unix operating systems, which have hierarchies with multiple levels.

To find an OS/400 object, you need the name of the library and the name of the object (in the form LIBRARY/OBJECT). An AS/400 object can only exist in a single library.

Although libraries cannot refer to other libraries, there is a single, special library called QSYS (containing all system objects), which can refer to other libraries.

General AS/400 commands

Below is a list of commands it is useful to know when working on an AS/400. Some of these commands are more useful for system administration purposes, others for programming.

All the commands are documented on the AS/400. To display help, type the command and press F4 to bring up the parameter entry screen. Then press the F1 key (or an equivalent "Help” key) to display the help corresponding to the command (make sure the cursor is positioned over the command’s first parameter, otherwise the help displayed will be for the first parameter and not the command itself).

General

DSPDBR Display database relations

DSPMSGD Display message description

DSPSYSVAL Display or modify the values of system variables, including the AS/400 serial number (QSRLNBR) and the default character coding (QCCSID)

DSPLIB Display a library

GO ASSIST Help menu for new users

GO LICPGM Shows a list of programs installed on the AS/400

STRSQL Start SQL/400

STRSEU Start the source code editor SEU

STRPDM Start Program Manager, for managing libraries, objects and members

SBMJOB Submit a job to the jobs queue

SAVLIB/RSTLIB Save/Restore a library

SAVOBJ/RSTOBJ Save/Restore an object

WRKJOBSCDE Work with job schedule entries

WRKOBJPDM Work with objects using PDM

WRKOUTQ Work with the output queue

WRKSYSSTS Work with system status

WRKSPLF Work with spooled files

WRKOBJLCK Work with object locks (jobs, members, records etc.)

WRKTBL Work with tables of characters

Libraries

ADDLIBLE Add an entry to the LIBL library

CHGCURLIB Change current library

Files

CHGPF Change the properties of a physical file

DSPPFM Display the contents of a physical file

DSPFD Display file description

DSPFFD Display file field description

UPDDTA Update data

Jobs

WRKSBMJOB Work with submitted jobs (batch)

WRKACTJOB Work with the system’s active jobs

WRKUSRJOB Work with user jobs

WRKJOBQ Work with job queues

DSPJOBLOG Display job log

DSPJOBD Display job description

Working with Transactions (Journaling)

CRTJRN Create a journal

CRTRCVJRN Create a journal receiver

STRJRNPF Start a journal physical file

DSPJRN Display a journal

Join logical files

Creating join logical files on the AS/400 is a solution to performance problems over low-speed networks.

The advantages of join logical files are :

The AS/400 establishes the links between files at the time of reading, thus limiting the number of exchanges with the PC.

The benefits of EASYCOM’s anticipated reading functions are gained.

The existing access routes for other logical files are re-used.

The join is dynamic, made at the time of reading, and incurs no cost on writing.

A join logical file is created by creating a DDS source compiled by a CRTLF …

Example :

R RFMT JFILE(AURA/SP_CUST AURA/SP_ORD)

J JOIN(1 2)

JFLD(CUST_ID CUST_ID)

CUST_ID JREF(1)

FIRSTNAME

LASTNAME

ORDER_ID

ORDER_DATE

K CUST_ID

For a join logical file, the search key only belongs to the 1st file.

Warning :

A join logical file can only be accessed in Read Only mode.

The Record Number returned after reading a Join logical file bears no relation to that of the physical file on which it is based.

The search key must therefore be used to access the physical file based on the join.

How is a join logical file created

The join file enables performance in accessing different files to be improved. It is particularly appropriate for tables with linked files, and provides considerable performance improvement.

On the AS/400, type STRPDM

Choose option 3, Work with members

File : QDDSSRC

Library : BIBLIO

F6 to create a new file

Source member : name_of_file

Descriptive text : …

Enter the description, on joining 3 files

F3 to quit, save Y for Yes

Option 14 to compile the member

Example :

R RFMT JFILE(AURA/SP_CUST AURA/SP_ORD)

J JOIN(1 2)

JFLD(CUST_ID CUST_ID)

CUST_ID JREF(1)

FIRSTNAME

LASTNAME

ORDER_ID

ORDER_DATE

K CUST_ID

Using an SQL view

The advantages of an SQL view are the same as those for join logical files, with the additional possibility of selecting the fields to be read.

Preparing the query on the AS/400 requires a little time.

The link between the Master and Detail files is made on the AS/400, and here again EASYCOM’s mechanisms for reading batches are used.

Sample queries :

SELECT EMPNO, LASTNAME, PROJNO

FROM CORPDATA.EMPLOYEE INNER JOIN CORPDATA.PROJECT

ON EMPNO = RESPEMP

WHERE LASTNAME > 'S'

SELECT EMPNO, LASTNAME, DEPTNAME, PROJNO

FROM CORPDATA.EMPLOYEE INNER JOIN CORPDATA.DEPARTMENT

ON WORKDEPT = DEPTNO

LEFT OUTER JOIN CORPDATA.PROJECT

ON EMPNO = RESPEMP

Installing and configuring the EASYCOM

Installing the EASYCOM Server

The EASYCOM server must only be installed once on the AS/400.

The installation is done from a Windows PC connected to the AS/400 through TCP/IP or APPC.

AS/400 configuration required

The EASYCOM server is compatible with all the versions of OS/400 supported by IBM since V3R2.

PC configuration required

PC with 80386/25 processor or higher

Operating system : Windows 95/98/NT/2000/XP

Connection using the TCP/IP protocol

The recommended, and most frequently used, protocol for connecting client workstations to the EASYCOM server is TCP/IP.

On the AS/400, TCP/IP must be installed, configured and started up.

See the AS/400 commands CFGTCP and STRTCP for more details.

TCP/IP on the AS/400

EASYCOM only uses the FTP server to install the server on the AS/400. For normal operation of applications, it can be shut down.

The EASYCOM subsystem must be started after starting TCP/IP. The EASYCOMD job runs permanently in the EASYCOM subsystem. It is automatically started on starting the subsystem.

To accept connection requests from client workstations, EASYCOM uses port 6077. If a security system or another application prevents the use of this port number, Configuring and administering the EASYCOM Serveur

TCP/IP on the Windows workstation

TCP/IP is one of the basic protocols installed on Windows systems. No other software is required to connect EASYCOM clients.

See also FTP connection refused

The EASYCOM server is made up of a set of objects (programs, commands and files) collected into a single library, called ‘EASYCOM’ by default.

Configuring the server installation :

Confirm the name of the installation library on the AS/400. Unless the installation is to test a new version, or in the case of a naming conflict, it is not recommended to change the name of this library. If the name is changed, the new name must be copied into the configurations of all the client workstations that will use it.

Installing the demonstration files.

For the first installation of EASYCOM on an AS/400, the demonstration files enable the test and demonstration programs installed on the client workstation to be executed from the development environment.

Choose the communications protocol.

By default, EASYCOM uses the TCP/IP protocol for communications between the client workstations and the AS/400 server. In this case, FTP is used to upload the EASYCOM server library. If the TCP/IP or FTP protocols are not available between the PC and the AS/400, use the SNA protocol, through an APPC router such as Client Access, or Microsoft SNA Server.

Give the name or the IP address of the AS/400 on which the software is to be installed.

Enter a user name and password to proceed with the installation.

It is not recommended to use any other user than QSECOFR. Certain objects in the EASYCOM library are configured to have QSECOFR as owner. The EASYCOMD (*PGM) object has to run with QSECOFR’s permissions.

If QSECOFR is not used for installing the server, the auto-configuration may not be completed, and the first start-ups may be difficult.

Operations carried out on the AS/400

Creating the EASYCOM library and restoring certain objects within it.

Operations carried out on the PC

Creating the \EASYCOM folder and specific subfolders and copying various files.

Configuring and administering the EASYCOM Serveur

On the AS/400, all the EASYCOM objects are in the EASYCOM library.

One further object is created when the server is first launched : object EASYCOM, type *FILE, library QGPL.

An entry for the EASYCOM library is automatically added to the list of libraries (ADDLIBLE) for each job started by client workstations. Therefore, it is not recommended that this be added explicitly to the 'users’ JOBD.

The following objects may undergo modifications after installation of the server on the AS/400 :

AURA *FILE Modified when the user license is registered.

EACSESSION : *FILE Modified when the user license is registered.

YPROCHDR : *FILE Modified by adding the description of a native AS/400 program that is to be called by client applications.

YPROCPARMS :

*FILE Modified when the calling parameters for AS/400 native programs are described.

If the EASYCOM server on the AS/400 is updated, these objects are restored to their new versions.

There are some objects that are created on installation, and can be recreated if necessary using the command : CFGEACTCP

This command enables the objects used for the connection of client workstations using TCP/IP to be created :

EASYCOM : *JOBD Subsystem in which client jobs are started.

EACJOBD : *JOBD Descriptions for client jobs.

EACJOBQ : *JOBQ Client job queue.

EACCLS : *CLS Class for client jobs.

EASYCOMD :

*JOBD Job description for the EASYCOMD job, which must always be active in the subsystem.

The CFGEACTCP command also enables you to change the subsystem name, and to change the number of the default port (6077).

Warning : Only one subsystem can be created for each EASYCOM library. To enable several subsystems, the library must be copied, and the command CFGEACTCP must be run in each library.

If the default port is changed, this must be specified for client connections (either at the prompt or in the configuration), in the AS/400 address, separated by a colon character ‘ : ’.

Machine name :pppp where pppp is the new port number.

Jobs on the AS/400

When the application is launched and a connection is established with the AS/400, a job is created on the AS/400.

This means that there is an active job for each instance of a connected client application.

Using APPC, the installed router creates a job on the AS/400 and EASYCOM communicates with this job using the APIs supplied by the router.

For an APPC connection, the jobs are in the QCMN subsystem, or QBASE if no communications subsystem has been defined.

Using TCP/IP, EASYCOM requires no extra software layer.

No router is needed. The EASYCOM DLLs are enough.

However, TCP/IP must be installed and configured on the client workstation and the service must be running on the AS/400.

EASYCOM on the AS/400 functions use a subsystem and a demon. The latter receives connection requests on behalf of client applications. When the application is launched, and a connection is made with the AS/400, a job is created on the AS/400. This means that there is an active job for each instance of a connected client application. Each application can therefore have its own files open, its own locks, current positions and current transactions.

Using TCP/IP, EASYCOM requires the presence of an EASYCOM subsystem and an EASYCOMD demon.

This demon will create a job on connection and EASYCOM communicates with the job via the standard TCP/IP APIs.

These jobs can be displayed using the commands WRKACTJOB or WRKSBSJOB on the AS/400.

Example :

EASYCOM jobs are independent, and have their execution environment created based on EASYCOM/EACJOBD in the case of a TCP/IP link, or the user’s JOBD in the case of APPC.

The job’s LIBL is the user's one.

This means that programs can benefit from properties and objects specific to the job, such as OVRxxx, QTEMP, *LDA, …

Note :

“EASYCOM” is the default name of the library for the EASYCOM server installation.

This library name may have been changed during installation.

After each IPL of your AS/400, the EASYCOM/EASYCOM subsystem must be started up :

STRSBS EASYCOM/EASYCOM

This command can be included in your system’s autostart (QSTRUP) for the next IPL.

QSTRUP is a CL program. To restore (RTVCLSRC) see : Connection error 10061 (Hex 274D) : Connection Refused

Priority of the "EASYCOMD" job

All jobs are stored in the EASYCOM subsystem.

The subsystem uses EACJOBD for its description and EACCLS for its priority class.

You can modify the subsystem’s priority class using the command CHGCLS.

Level of authority of the "EASYCOMD" job

By default, "EASYCOMD" is a QSECOFR-type job.

It should have the *ALLOBJ option to function in the best conditions.

Activation Key

The activation key is calculated from the AS/400’s serial number. To find this number, type the command DSPSYSVAL SYSVAL(QSRLNBR) on a terminal.

On an AS/400 terminal, enter CHGCURLIB EASYCOM, press Enter, then EASYREG, press Enter, and enter the key parameters provided by Aura Equipements :

License . . . . . . . . . . . . ACEIDA

Special Development License *NO or *YES

Company name . . . . . . . . . . 'Name_of_your_company’

Activation Key . . . . . . . . . Your_key

Number of connections . . . . . As on the license

Authorized partition ID (1->n) 0

EASYCOM'S Version . . . . . . . 3

EASYCOM'S Options . . . . . . . 0

Expiration date (ddmmyyyy) . . . 00000000

Authorized Proc. group. . . *

Extended license *NONE

Warning : Distinguish between O (letter) and 0 (digit) and between I (letter) and 1 (digit).

It is recommended to disconnect any EASYCOM connections before entering the key(s).

Note :

Protecting access to EASYCOM

Easycom takes care of security at user level : an Easycom program can be used on a given AS/400 after validation of a user name and password on the system. The processes carried out by the program will be executed under the identity of the user. All AS/400 permissions will be respected.

1. Program level security

In addition to the basic security, security at program level can be used. Only those programs approved by the IT department can be used on the AS/400.

Non-approved EASYCOM programs will be able to connect to the AS/400 using EASYCOM, but will not be able to carry out any operations (opening files, calling programs etc.).

An approved program will have to send a special password to Easycom

See the Easycom Client section of the documentation.

An AS/400 program written by the IT department will send back a response as to whether the password is accepted. This password could for example correspond to the coding of the Easycom program.

Following this command, the AS/400 displays the following screen.

Make your choice and press ENTER.

Easycom server library name

EASYCOM Alpha value

Easycom server job priority

0 Number

TCP/IP Keep Alive frequency

120 Seconds (0 = No Heart Beat)

Delay before asking again pwd

0 Seconds (0 don't ask for password)

Delay before automatic SIGNOFF

0 Second (0 no auto signoff)

Easycom Log File level 0 0 = No log file generated

Print the clock in Log File

*NO *YES, *NO

Automatic Keep Alive start

*YES *YES, *NO

Detailed Job Log *NO *YES, *NO

Lock Easycom host *YES *YES, *NO

If the “Lock Easycom host” entry is set to *YES in the CFGEAC, no file can be opened, no program can be called, and no command can be sent to the AS/400 by EASYCOM, until a PC application unlocks it.

The PC will unlock the connection by a special programming option.

This option requires a script called EACP003 to be written. This script must be in the *LIBL of the EASYCOM job.

Here are the bare bones of the script :

PGM PARM(&PASSW &RESULT)

DCL VAR(&PASSW) TYPE(*CHAR) LEN(100)

DCL VAR(&RESULT) TYPE(*CHAR) LEN(10)

GEN_EACUNLOCK.htm

…

/* IF PASSW HAS THE RIGHT VALUE */

CHGVAR VAR(&RESULT) VALUES('*YES')

…

/* IF PASSW DOES NOT HAVE THE RIGHT VALUE */

CHGVAR VAR(&RESULT) VALUES('*NO')

2. Security by restriction

It is also possible to restrict the use of Easycom to a group of users and/or a group of PCs.

To do this, a validation program called EACTCP003 must be written in the Easycom library.

Interface of the EACTCP003 program :

PGM PARM(&TPPGM &TPLIB &USER &EAC_PARM1 + &EAC_PARM2 &RMT_ADR &JOBNAME)

DCL VAR(&TPPGM) TYPE(*CHAR) LEN(10) DCL VAR(&TPLIB) TYPE(*CHAR) LEN(10) DCL VAR(&USER) TYPE(*CHAR) LEN(10) DCL VAR(&EAC_PARM1) TYPE(*CHAR) LEN(30) DCL VAR(&EAC_PARM2) TYPE(*CHAR) LEN(30) DCL VAR(&RMT_ADR) TYPE(*CHAR) LEN(50) DCL VAR(&JOBNAME) TYPE(*CHAR) LEN(10)

Parameters :

TPPGM : Target Program Name

Name of the server program to execute; “Easycom” by default.

TPLIB : Library containing the target program TPPGM

USER : User name

User name for the new client connection (may be used to restrict access to a group of users)

EAC_PARM1 : First parameter of program TPPGM

Parameter to be sent if you do the SBMJOB yourself.

EAC_PARM2 : Second parameter of program TPPGM

Parameter to be sent if you do the SBMJOB yourself.

RMT_ADR : Caller’s TCP/IP address

Caller’s TCP/IP address (may represent a group of workstations)

JOBNAME : Name of the job for SBMJOB

Name of the job within the Easycom subsystem, the name of the client workstation by default.

If the JOBNAME has the value *NO, the EASYCOM job will not be started.

If the JOBNAME has the value *YES, the EASYCOM job will be noted, but it will have to be started by the EACTCP003 program.

Example :

EACTCP003 can verify the user’s permissions and TCP/IP address, and carry out the following operations :

Permit execution :

In EACTCP003, leave the &JOBNAME variable unchanged, or replace by another job name, and then quit normally.

Refuse execution :

In the EACTCP003 program, change the value of &JOBNAME to ‘*NO’, and quit normally.

CHGVAR VAR(&JOBNAME) VALUE('*NO')

Execute the target program :

In EACTCP003, launch the target program using a SBMJOB and modify the value of the &JOBNAME variable to ‘*YES’.

CHGVAR VAR(&JOBNAME) VALUE('*YES') SBMJOB CMD ( CALL PGM(&TPLIB/&TPPGM)+

PARM (&EAC_PARM1&EAC_PARM2)) JOBD(&TPLIB/EACJOBD) + USER(&USER) RTGDTA(*JOBD)

Installation errors

Error validating the activation key

First of all, stop all current jobs on the AS/400.

Next check the AS/400’s serial number – the activation key depends on this information.

Only the DSPSYSVAL SYSVAL(QSRLNBR) command will give the correct value.

If the number corresponds, find out which version of OS/400 you are using, with the command GO LICPGM (option 10, then F11 - Edition).

If the version is V4R2 or higher, go through DFU to enter the key.

To do this, enter the command UPDDTA EASYCOM/AURA.

When the file is open, scroll through the records until you find a LICENSE entry.

The following list gives the fields to be entered, as well as their equivalents on the fax or mail that was sent to you :

AS FIELD FAX FIELD COMMENTS

RAISON Company Name ALL IN CAPITALS!

CONNEX Number of simultaneous sessions

Number of simultaneous connections (1, 3, 10, 20, 0)

DATE Expiration Date 00000000 for a definitive key, formatted over 8 characters

CLEF Activation Key Capital letters, distinguishing between 0, O, 1 and I

POSTES Number of simultaneous stations

0

OPTIONS Option

The other fields, COPYRIGHT, FILLER, FILLER2, VERSION and MODELE should not be modified.

Important :

Once the key has been entered on the AS/400, it does not need to be entered on the PC !

The PC module is only used to check the key entered.

To use it, give the LICENSE in the corresponding entry, and tick the “Development License” box if you have a development license.

Finally, click on “Check existing”, which will verify that the parameters have been entered correctly.

Examples of errors returned

Error 1 : Code incorrect. Check all parameters.

Check that the AS/400 number displayed by the error corresponds to the one shown on the activation key documentation.

Error 6 : Check that no users are connected, using the command WRKOBJLCK and

Object : AURA or eacsession

Lib : Easycom

Type : *File

If everything happens as normal, you should see the message : “No lock for this object”

FTP connection refused

Installation via TCP/IP uses FTP.

This requires that the FTP service on the AS/400 be launched using the command :

STRTCPSVR SERVER(*FTP)

Native Programs

Describing AS/400 native programs

See also : Using programs or Data queues

EASYCOM enables you to call AS/400 native programs, CL or RPG programs or stored procedures.

To allow this, EASYCOM needs the description of these programs, which it stores on the AS/400 in the files YPROCHDR and YPROCPARMS in the EASYCOM library.

The description of the programs and the data queues is built with the DTAQ-RPC constructor on the PC. The basic principle consists of specifying all parameters, their types and their uses (input, output, input/output) for calling the program.

The first screen presents the existing procedures (stored on the AS/400) and enables procedures to be created, modified or deleted. You can also save the descriptions in a text file on the PC for later transfer to another AS/400.

A new name is given to the procedure, which does not need to match the program that is to be associated with it.

A native AS/400 program (CL, RPG, COBOL, C etc.) is associated with the procedure.

The library may be omitted, or replaced by *LIBL.

The description is a free text field, which will be visible when client workstations browse through the procedures.

Each calling parameter of the program is described, giving its type and size.

Each parameter can be considered as a field in a database table.

It therefore has a name, by which it can be referred to by the application.

Parameters designed to provide values for the called program are considered as input parameters (IN).

Parameters designed to receive a value on returning from the call are considered as output parameters (OUT).

Parameters that are modified by the program are both input and output (IN/OUT).

By default, all the parameters in an AS/400 program are both input and output. The logic of the program can change this property.

If a calling parameter of the program is a structure (DS : Data Structure), each field of the DS has to be described individually. But, for the first field only, the box to be ticked is : This field is a parameter or the 1st Field.

The type of parameter expected by the AS/400 program must be specified exactly :

CHAR (A) : Character data type.

BIN2 (B) : 16-bit numeric data type.

BIN4 : 32-bit numeric data type.

PACK (P) : Condensed numeric data type (DECIMAL).

This is the format in which CL handles numerical data (CL *DEC type).

ZONED (S) : Extended numeric data type (NUMERIC).

DATE (L) : AS/400 date in the format yyy-mm-dd.

TIME (T) : Time in the format hh :mm :ss.

FLOAT (F) : Numeric value in single-precision floating point.

DOUBLE : Numeric value in double-precision floating point.

TIMESTP (Z): Elapsed time field.

GRAPHIC : Character type data, not to be converted.

EXTERNAL DS : A structure described by an external data structure, i.e. a physical file.

Calling a ILE Procedure

The ILE procedure must be described, like a program (Type *PGM).

The AS/400 object in the field "AS/400 Object Name" is type *SRVPGM.

The type must be "Service Program".

The first parameter described corresponds to the return value of the procedure.

Only return values type "Integer 32 bits" are accepted.

Then, the parameters are described, as for a program.

Only 16 parameters maximum are accepted for the procedure, plus the return value.

For each parameter, the option “By Value” can be checked on.

This option is valid only for parameters type "Integer 32 Bits".

When it is on, this option indicates that the procedure receives this parameter by value, and not by address.

Using programs or Data queues

In the import utility, just specify the specific values "*PGM" or "*DTAQ" as the library name.

Proceed with the rest of the import as you would for any other type of file.

Comments :

If your data queue is of FIFO type, the virtual file will have a single key on the first field.

If your data queue is of KEYED type, the virtual file will have a composed key of the first four fields.

If this is a program, the virtual file will have a key field for each input (or input/output) parameter.

NB : To DATQ, 3 parameters are necessary.

Migrating procedures and data queues from one AS/400 to another

When a developer working on an AS/400 creates procedures and data queues which will subsequently have to be used on another AS/400, the descriptions of these procedures and data queues have to be transferred to the new AS/400.

The descriptions are stored in three files :YPROCHDR, YPROCPARMS and YPROCPGM. They are stored by default in the EASYCOM library on the AS/400, but they can be placed in another library, where they will be searched for by the LIBLE of the connected profile.

If the two AS/400s are connected, the above three files can obviously be transferred directly from one to the other.

Otherwise, the DTAQ-RPC constructor offers a facility to import/export descriptions from or to text files, meaning that the necessary descriptions can be saved on the developer’s workstation and then restored on the customer’s.

AS/400 trace file EASYCOM

AS/400 trace file

Trace files enable the operations carried out by EASYCOM, on the client or server side, to be visualized. The EASYCOM server on the AS/400 processes elementary requests applying to tables or procedures. It receives a request for a process over the network. And returns a response.

The requests and responses can be recorded in a trace file, and this file can serve as a basis for analyzing the flow of data circulating between the client and the server.

Lines starting with << indicate the receipt of a request.

Lines starting with >> indicate the AS/400’s response being sent.

<<EACopen(EASYCOM/SP_CUST,4194309,-1) ß Request. 9 Fields, 0 key fields EAC_NO_CVT - mode= >>Ret=1; Err=0; Msg=; Int=0 ß Response.

In the AS/400 trace, if the timer option has been selected, all the requests and responses are preceded by the time in the format hh :mm :ss.ms.

<<15:48:45.566: EACread(1,p(2275),91,34144281,(null),0,p(100))

In the response, the data “Clk=x” indicates the CPU time used by the AS/400 to process the request.

>>15:48:45.574: Clk=8, Len=619; Ret=5; Err=0; Msg=; Int=0

Trace of reading records from a file

<<EACread(2,p(816),102,34144264,(null),0,p(32))

VERB=_EAC_NEXT LOCK=OFF RECS=8 FILE=EASYCOM/SP_CUST_UN

RRN=2 RRN=4 RRN=5 RRN=6 RRN=7 RRN=8 RRN=9 RRN=10

>>Ret=8; Err=0; Msg=; Int=0

The type of read operation is indicated by “VERB=

Where xxxx may be :

FIRST, NEXT, PREV, LAST, KEY_EQ, KEY_GE, KEY_GT, …

“LOCK= indicates whether the operation is being carried out with or without record locks.

“RECS= indicates the maximum number of records requested in the response.

This number is directly linked to the “Records=” data in the “Buffers” section of the “Easycom.ini” file on the client PC, or to the data given by “ASPropriete” in the WinDev program.

“RRN= indicates the number of records read.

In response, “Ret=n” indicates the number of records actually returned, following the read request.

If the read operation fails through an input/output error, the message is stored in the trace, and the records actually read are returned.

<<EACread(2,p(3570),102,34144291,(null),0,p(140)) VERB=_EAC_NEXT LOCK=OFF RECS=35 FILE=EASYCOM/SP_CUST_UN RRN=11 RRN=12 RRN=13 RRN=14 RRN=15 RRN=16 RRN=17 RRN=18 RRN=19 RRN=20 RRN=54 +... ... RRN=55 RRN=56 **SIGIO** Msg :CPF5001 >>Ret=13; Err=5001; Msg=CPF5001; Int=0

In this example, 35 records are requested, but only 13 are available before the end of the file.

To obtain the detailed error message, use the command DSPMSGD on the AS/400.

Trace of the opening of a logical file <<EACopen(EASYCOM/SP_CUST_UN,4194309,-1) LF with 1 Data Members, 1 Record Formats 9 Fields, 1 key fields EAC_NO_CVT - mode=rr+ >>Ret=2; Err=0; Msg=; Int=0 <<EACgetdesc(2,p(65000),65000,939786240,(null)) >>Ret=9; Err=0; Msg=; Int=0

Trace of the opening of a physical file <<EACopen(EASYCOM/SP_CUST,4194309,-1) 9 Fields, 0 key fields EAC_NO_CVT - mode=rr+ >>Ret=1; Err=0; Msg=; Int=0 <<EACgetdesc(1,p(65000),65000,939786240,(null)) >>Ret=9; Err=0; Msg=; Int=0

Trace of opening an SQL query

<<EACopen(SELECT * from SP_CUST where LASTNAME>'M',4194309,-1)

Statement :SELECT * from SP_CUST where LASTNAME>'M'

Cursor 0


<<EACgetdesc(2,p(65000),65000,939786240,(null))


Trace file header, common to all sessions

This part of the trace file is always the same for all EASYCOM for WinDev sessions.

Time is : 03/27/2000 - 17:22:10 Easycom Server Version is : 4.5712, Link is TCP/IP Client license is : D$WINDEV55 , Easycom Library is : EASYCOM JobName=ALBATROS, User=QPGMR , QCCSID=297 Heart Beat freq :10 Easycom Log File TRACE/SR, level 1 ------------------------------------------------------

>>Ret=1; Err=0; Msg=; Int=0 <<RTV_AS_VER(p(4)) >>Ret=4; Err=0; Msg=; Int=0 <<WriteTableEBCDI(49 42 4D 43 43 53 49 44 20 30 20 31 32 35 32 00 00 00 00 00 ...(256)) Build Table from CCSID:0 to 1252 open IBMCCSID01252, IBMCCSID000000000100 <<WriteTableASCII(49 42 4D 43 43 53 49 44 20 31 32 35 32 20 30 00 00 00 00 00 ...(256)) Build Table from CCSID:1252 to 0 open IBMCCSID00000, IBMCCSID012520000100 <<ReadTableASCII(p(256)) >>Ret=0; Err=0; Msg=; Int= <<ReadTableEBCDIC(p(256)) >>Ret=0; Err=0; Msg=; Int=0 <<EACSqlDeclare(2A 45 41 43 20 43 56 54 20 4E 4F 00 ,12) Statement:*EAC CVT NO >>Ret=1; Err=0; Msg=; Int=0 <<EACSqlBegin() >>Ret=0; Err=0; Msg=; Int=0

Errors while connecting

Connection with `Rallye'

Rallye 6.2 is not based on the standard APPC API supplied by IBM.

EASYCOM needs this API for correct APPC communication and to benefit from all the services.

What is the best way to connect ?

TCP/IP is currently by far the best solution.

It avoids the use of a router, ensures safe communication of the data, and gives better performance.

Connection error 11001 (Hex2AF9) : Host not found

The AS/400 is designated by its name on the TCP/IP network.

Check the name. The TCP/IP network could not find it either on the local system or on a DNS server.

Check the AS/400 name, the DNS servers, or use an IP address of the form xxx.xxx.xxx.xxx

Where is the Hosts file located ?

With Windows NT for example, the "path" is c:\WINNT\system32\drivers\etc

You need to find : IP Address, followed by a tab and the machine name.

Connection error 10060 (Hex 274C) : Connection Time out

The TCP/IP address contacted does not exist on the network.

Check the AS/400’s TCP/IP address or its name.

If an AS/400 machine name is used, check that it is properly referenced on the DNS servers.

Connection error 10061 (Hex 274D) : Connection Refused

Check the IP address or the name of the AS/400.

Check that the EASYCOM system has been properly launched on the AS/400.

Launch the subsystem using the command : STRSBS EASYCOM/EASYCOM

If the subsystem has been started, check that the EASYCOMD job is running.

If not, start the EASYCOMD job with the command : STREACD EASYCOM

Or, stop the subsystem and restart it.

Test the connection using the EASYCOM configuration or administration tool.

If the EASYCOMD job never starts, check the messages that EASYCOM may generate using the following commands :

DSPMSG EASYCOM/EACMSGQ

or

DSPPFM EASYCOM/LOGFILE

By default, EASYCOM uses port number 6077.

If this number is already in use, Configuring and administering the EASYCOM Serveur

Error of the form "APPC error 63, primary xxxx secondary yyyyy"

In general, this error means that there are problems with the configuration of the router.

It also appears when using Netware for SAA version 2.0.

Warning : this version must be updated using patch number SAA016.EXE from Netware for SAA.

Obtain this patch from your supplier.

Error 0ffffffffc = error -4

Error of the form "APPC error xx, primary yyyyy secondary 0x274D (Hex)

This error means that the connection has been refused or the remote service does not exist.

To work under TCP/IP on the AS/400, EASYCOM launches a subsystem (EASYCOM) and then a demon (EASYCOMD, which runs in the EASYCOM or QSYSWRK subsystem).

If the subsystem is not active, restart it using the command STRSBS EASYCOM/EASYCOM, and then check that it is present.

If the demon does not exist, stop the subsystem (ENDSBS EASYCOM *IMMED) and restart it.

If nothing works, an error message is written in the EASYCOM MSGQ (DSPMSG EASYCOM/EACMSGQ).

To avoid having to restart the subsystem on each IPL of the AS/400, include the subsystem start command in QSTRUP.

QSTRUP is a CL program. To modify it, 3 stages are involved :

Extract the CL source code using the command RTVCLSRC QSYS/QSTRUP

Modify the source code

EAC_Connection_using_NSRouteur.htm

Recompile the CL program using the command CRTCLPGM. Weed out any compilation errors.

Common problems

The subsystem never starts

At any time, the EASYCOM subsystem can be started with the command:


The start up of the Easycom subsystem should be added in the QSTRUP program.

At the and of the existing QSTRUP procedure, add the following lines:

DLYJOB DLY(10)

ADDLIBLE EASYCOM


The job EASYCOMD must be running in the subsystem.

This job is started automatically when the subsystem is started.

It can be started at any time with the command:

STREACD LIB(EASYCOM)

Connection using NSRouteur

Check that the parameters are correct (16 or 32 bits).

For example, for ClientAccess, it is possible to check the type of access the router is making.

Look in the “ClientAccess Properties”, “Other” tab, and check the heading “16-bit support for ClientAccess Client”.

Next check the router you are using (NetSoft, etc.).

How can I recover 36 files ?

If the 36 file has an associated IDDU, it is seen as an AS/400 file.

If there is no description :

Create an empty AS/400 file with the desired description,

In the alias file, add *FMT=name_of_format_file following the name of the data file (36), and, if necessary, after each key.

How can I avoid the loging screen ?

A tip for giving the user name and password in advance is to enter them into the Easycom.ini file, which is located in the Windows folder.

To do this, enter the following lines (for example) in capitals into the [GENERAL] section :

Uid=

Pwd=

In this case, the values are written transparently into the file, and no encryption is applied.

Message "E32APPC.DLL not found"

With APPC, we need the E32APPC.DLL file to be present in a folder mentioned in "PATH" or in the folder Windows\System32.

Just move the DLL into one of these folders.

The E32APPC DLL is part of the ClientAccess or NetSoft router.

What should I check if I cannot connect to the AS/400

1/ The address

Each PC has its own physical address on the network. This address takes the form of 4 groups of 3 digits.

Example : 194.206.160.100

The last group can range from 0 to 255, meaning that on a single local network there can be no more than 255 machines.

On your PC, select Programs from the Start menu, and then MS-DOS Prompt. The MS-DOS shell window is displayed.

Enter the command "ping xxx.xxx.xxx.xxx" (where xxx.xxx.xxx.xxx is the IP address assigned to the AS/400).

The MS-DOS PING program tries to communicate with the computer having this IP address, and displays the result of the operation. If it has failed (a time-out message is displayed), close the MS-DOS prompt window by entering the “exit” command.

This method will tell you if the AS/400 address is correct.

2/ The name

There are rules enabling you to find an IP address from a name.

- Hosts file : The DHCP server (Dynamic Host Configuration Protocol) allocates addresses for different PCs dynamically. The “hosts” text file, located for example in c:\winnt\system\drivers\etc\hosts, associates machine names with IP addresses.

- DNS (Domain Name System) : Select the properties of the Network Neighbourhood icon. On the Protocols tab, double click on TCP/IP protocols, and then check the host name on the DNS tab.

Important : Not to be confused with the SNA name.

Check on the AS/400, the Server version

Easycom Server version (on the AS/400)

Or, on a terminal session, enter the command :

CALL EASYCOM/EASYCOM *VERSION

Display the processor group

To know the processor group on your AS/400 when EASYCOM or LAUNCHER are not installed :

On a Terminal session with the QSECOFR user profile, enter the command : WRKLICINF <Enter >

The screen displays :

WORK WITH LICENSE INFORMATION S650643C

20/01/04 16:22:21

SYSTEM SERIAL NUMBER . . . . . . . . . : 650643C

PROCESSOR GROUP . . . . . . . . . . . : P05

TYPE OPTIONS, PRESS ENTER.

1=ADD LICENSE KEY 2=CHANGE 5=DISPLAY DETAIL 6=PRINT DETAIL

8=WORK WITH LICENSE USERS ...

LICENSE

OPT PRODUCT TERM FEATURE DESCRIPTION

5722SS1 V5R2M0 5050 OS/400

5722SS1 V5 5051 OS/400

5722SS1 V5R2M0 5103 OS/400 - Extensions support et stockage

5722SS1 V5 5109 OS/400 - NetWare Enhanced Integration

5722SS1 V5R2M0 5112 OS/400 - PSF/400 1-45 IPM Printer Support

Enter <Entrer> or <F3> to quit this screen.

Manual installation of EASYCOM Server

All commands must be run with QSECOFR user profile.

There must be EASY310.BD and DEMOEAC.BD file in the <install directory>”\server" directory.

Enter on an AS/400 terminal :

CRTLIB EASYCOM

CRTSAVF EASYCOM/SAVF

On the pc, use FTP to transfer EASY310.BD file into EASYCOM/SAVF.

(D’ont forget to use the binary transfer type with the bin command).

Then restore the objects using the terminal :

RSTOBJ OBJ(*ALL) SAVLIB(YEASY310) DEV(*SAVF) SAVF(EASYCOM/SAVF) RSTLIB(EASYCOM)

On the pc, use FTP to transfer DEMOEAC.BD into EASYCOM/SAVF.

Then restore the objects using the terminal :

RSTOBJ OBJ(*ALL) SAVLIB(YDEMOEAC) DEV(*SAVF) SAVF(EASYCOM/SAVF) RSTLIB(EASYCOM)

Then run the following commands to configure TCP/IP and Easycom :

CHGCURLIB EASYCOM

CFGEACTCP EASYCOM

EACINSTALL

NB : Le EASYCOM subsystem is now running and EASYCOMD present in it.

To finish, Enter the key activation :

CHGCURLIB EASYCOM

EASYREG

Appendices

How to contact Technical Support ?

If you have not found the solution or explanation for your problem here, please contact EASYCOM technical support.

E-Mail :

[email protected] AURA Equipements

Z.A. de Courtaboeuf

10, Avenue du Québec Tel. : 33 (0)1 69 07 01 45

BP 519

91946 LES ULIS CEDEX

FRANCE Fax : 33 (0)1 64 46 29 06

Internet : http://www.easycom-aura.com/

For general or sales information contact : [email protected]

WARNING !!! AURA Equipements propose you several levels of technical support.

Contact us to receive the best offer corresponding to your needs.

Changing your AS/400

If you change your AS/400, the activation key(s) that you have will no longer be valid for the new AS/400.

Every license is granted for a specific company and a specific AS/400.

To make this change, print out, complete and return to us the following form :

What needs to be removed on the old AS/400 ?

- The EASYCOM library.

Form on :

http://www.easycom-aura.com/doccom/attestchange_vf.pdf

User License

Ownership of the Software

1. The Easycom For Delphi software programs (« Software ») and accompanying written materials (the « Documentation ») are owned by AURA Equipements (« Licensors ») and are protected by International copyright laws and by international treaties. The Easycom engine is a product that is the sole propriety of AURA Equipements.

Definitions

2. End User : The End user is either the natural person or the legal subject that bought the license or that uses an Evaluation Version.

3. Evaluation Version : Your use of the software is for the purpose of evaluating whether to purchase an ongoing license to the Software. You use an Evaluation Version when you install the Software without the appropriate serialization code (which takes the form of a serial number) to be install system. When you use an Evaluation Version, as soon as the DLL files in the Software are called upon, will be prompted before a dialog box appears explaining that you are running an Evaluation Version of the Software. You will then receive about twenty minutes of time to use the product by a similar dialog box every minute after one hour of use. The total number of time you can use the DLL is limited to 100. Anyhow the case the evaluation period for use is limited to 15 days.

4. Software : Software is the right to use the software-product "EASYCOM Server" and the Easycom For Delphi a direct level access for a PC Side for one development tool.

(a) Installation : The "Easycom For Delphi" software, includes two parts : the client part and the server part. The client part is to be installed on the PC which one is linked to the AS/400. The server part is to be installed on the AS/400.

(b) You can install the server part only once at a time one a specific AS/400 machine. (The software activation key is calculated by using the AS/400 serial number). In case, the software is to access to several AS/400, you have to purchase a license for each AS/400.

(c) The client part can be installed on as many PC's you want. But only as many PC's as the number of users of the license will be able to access the AS/400 at a time. (The activation key is calculated by using the number of users too)

(d) The evaluation version includes only one server part, one client part with one single connection.

4.1 The "Easycom For Delphi developer" gives to the developer all the functions requested for the development of an application.

4.2 The "Easycom For Delphi runtime" gives to the user the possibility to execute the application, which has been developed with "Easycom For Delphi developer". You can not develop any application with "Easycom For Delphi runtime".

4.3 The evaluation version is "Easycom For Delphi developer" limited for a period of time.

5. Maintenance release : shall mean corrections of errors and minor additions or improvements of functions in the software that are released to the public by Licensor from time to time at its sole discretion. A new maintenance release is identified by a modification of the product numbering to the right of a decimal point (e.g., a released labeled « 4.1 » would be a maintenance release of version 4 or 4.0 of the software).

6. New Version : shall mean important additions of improvements of functions or modules in the software that are released to the public by Licensor from time to time at its sole discretion. A New Version is identified by a modification of the product numbering to the left of decimal point (e.g., a move from « 4.1 » to « 5.0 »). Licensor maintains full discretion as to whether and when to issue a new release of the Software and whether to classify a new release as a « Maintenance Release » or « New Version ».

Grant of License

7. License for Evaluation : You may use the Evaluation Version of the Software and Documentation in accordance with the terms of this Agreement (except that you will not benefit from the rights set forth in sections 9,18,22 and 23 below) and solely for the purpose of deciding whether to purchase a full License to the Software. You may also reproduce and distribute, including by means of posting on an Internet forum, the un-installed Evaluation Version of the Software known as the « install disks », provided you do not modify or delete this agreement, any copyright or trademark notices or any portion of the Software. You shall be solely responsible for any costs or liabilities arising from any such reproduction or distribution.

8. Acquisition of Full License : If you have an Evaluation Version of the Software and wish to benefit from the rights set forth in sections 9,18,22 and 23 below, you must obtain a serialization code, which will disable the evaluation dialog prompt cycle described in section 3 above. A Serialization code may be obtained, in exchange for the applicable Licensee fee, simply by contacting Licensors or any authorized AURA Equipements distributors, the coordinates of which are set forth below.

9. License : In consideration for the payment of the License fee and your agreement to abide by the terms of this agreement, Licensor grants non exclusive License to use the Software and the documentation depending on (i) number of Client Licenses bought (ii) the price paid Software Development and/or Software Run Time, connected to a single server.

Governing Law : This agreement shall be governed by the laws of the United States and all the signature of the international copyright treaties.

Reference : DP-USER$032005

Glossary

ADO

The general ActiveX library gives access to databases. The library is based on the use of OLE

DB drivers, and enables both native and SQL access. Access to the AS/400 is made possible

using Easycom OLE DB.

APPC

"Advanced Program-to-Program Communication" is a communication protocol and programming interface.

ASCII

"American Standard Code for Information Interchange"

128 possible combinations, which enable the representation of 96 printing characters (the letters A to Z in upper and lower case, the digits 0 to 9, and a variety of punctuation symbols) plus several non-printing control characters, such as carriage return, form feed and backspace.

ASCII is the basis for the character set used on PCs under Windows and DOS.

Values higher than 128 vary depending on the language being used (consisting of accented or special characters).

There are several ASCII codes defined by their CCSID.

CCSID

"Coded Character Set Identification"

It indicates a number in the nomenclature of the character sets. That gathers all the character sets: ASCII, EBCDIC, DBCS or SBCS.

For example French code EBCDIC is number 297, the ASCII code Windows Latin-1 is the 1252.

Citrix Citrix is a centralized IT server solution, where all applications and data reside and run on the

server. Citrix uses ICA technology for sending information to clients, with only mouse clicks,

screen updates and keyboard events using the network.

DLL Files used by Windows applications, which contain specific functions. In order for them to be

found correctly by the program, they must either be in the program’s own folder or a folder

listed in the system “PATH”.

DNS A name and address resolution service that uses a distributed database containing the

addresses. DNS simplifies access to computers by referring to them by name rather than by a

numeric address. DNS is the name/address resolution service used by the Internet.

EBCDIC

"Extended Binary Coded Decimal Interchange Code" – an 8-bit code.

This code is principally used on large IBM systems and the AS/400. EBCDIC codes exist for all countries. See CCSID.

FTP A TCP/IP protocol, service and application for copying files from one computer to another.

Before the server transfers a file, it asks the client to provide a valid user name and password.

Anonymous FTP is used by public network sites. This enables files to be transferred using a

standard “anonymous” user name, with the user’s email address as a password.

IP Address s stored in 32 bits, used by a computer on a TCP/IP network. The IP address is made up of

two parts : a network number and a host number. See Ipv4 and Ipv6.

Java

A multi-platform object-oriented programming language.

JavaScript

A scripting language used in client-side (web browser) html pages to make them more dynamic.

JDBC

"Java Database Connectivity" – a Java driver for database access.

Logical file

A logical file is external, as is a physical file, so a logical file can be used to redefine the record format in a program.

The use of multiple logical files for a single physical file enables the use of alternative access paths, and the sharing of data between different programs.

One very important point is that all the programs are looking at the same physical data – there is only one physical copy.

Physical file This contains the description of the data, and the data itself. The description is frequently

referred to as a description of an external file, and we say that the two systems, AS/400 and

System/38, have data described externally. The advantage of this is that the program does not

need to contain definitions of the data, and so the program does not define how the data should

be physically stored on the system. Similarly, a single program can work on files containing

data structured according to different formats.

Ping

"Packet Internet Groper"

A program that sends an ICMP echo request to a remote computer and awaits its response that it is accessible to the network.

The command enables the presence of a machine to be verified, as the service is run in all TCP/IP configurations.

easycom for delphieasycomstore.com/data/webhelp/easycom_delphi/easycomfordelphi.pdf · easycom for...

Documents