tcaccess - host server module - treehouse software, inc. · tcaccess version 8.0.0 host server 1....

tcACCESS Version 8

Host Server Module

Last review: 01/13/2011

Host Server tcACCESS Version 8.0.0

T a b l e o f c o n t e n t s

1. Host Server Modules.............................................................................................................................................71.1 Basic Access Modules.....................................................................................................................................8

2. SQL Engine.........................................................................................................................................................102.1 Introduction...................................................................................................................................................102.2 Activation and Administration......................................................................................................................13

2.2.1 System Entries........................................................................................................................................132.2.1 User Entries............................................................................................................................................14

2.3 SQL Engine Commands and Statements.......................................................................................................152.3.1 Comments and Optional Statements.......................................................................................................152.3.1 The CALL Statement.............................................................................................................................182.3.2 The COMMIT Statement.......................................................................................................................192.3.3 The DELETE Statement.........................................................................................................................192.3.1 The INSERT Statement..........................................................................................................................192.3.1 The NOCOMMIT Statement.................................................................................................................202.3.2 The ROLLBACK Statement..................................................................................................................202.3.3 The SELECT Statement.........................................................................................................................22

2.3.3.1 The SELECT Clause.......................................................................................................................222.3.3.2 The FROM Clause..........................................................................................................................232.3.3.3 The WHERE Clause........................................................................................................................232.3.3.4 The EXIT_SET_WHEN Clause.....................................................................................................232.3.3.5 The EXIT_ALL_WHEN Clause.....................................................................................................23

2.3.4 The GROUP BY Clause.........................................................................................................................272.3.4.1 The HAVING Clause......................................................................................................................27

2.3.5 The UNION clause ................................................................................................................................282.3.6 The ORDER BY Clause.........................................................................................................................282.3.7 The UPDATE Statement........................................................................................................................282.3.8 Expressions.............................................................................................................................................29

2.3.8.1 Operators.........................................................................................................................................292.3.8.2 Constants.........................................................................................................................................292.3.8.3 The NULL Constant........................................................................................................................30

2.3.9 SQL Functions........................................................................................................................................312.3.9.1 Single Functions..............................................................................................................................312.3.9.2 Grouping Functions.........................................................................................................................57

2.4 Precompiled SQL-Statements ......................................................................................................................592.4.1 The Precompilation................................................................................................................................592.4.2 The execution using EXECUTE............................................................................................................61

2.5 Tables and Views Definition.........................................................................................................................622.5.1 Table Definition.....................................................................................................................................62

2.5.1.1 Key word HOSTFILE=...................................................................................................................622.5.1.2 Key word FIELD=..........................................................................................................................632.5.1.3 Key word STRUCTURE=..............................................................................................................662.5.1.4 Key word RECEXIT=.....................................................................................................................662.5.1.5 Key word INSERT_INITIALIZE=.................................................................................................662.5.1.6 Key words for TS Queues...............................................................................................................662.5.1.7 Keywords for TD-Queues...............................................................................................................682.5.1.8 Key words for VSAM Files.............................................................................................................682.5.1.9 Keywords for DL/I Segments..........................................................................................................692.5.1.10 Key words for MVS PS/PDS Files................................................................................................792.5.1.11 Keywords for DB2 or SQL/DS.....................................................................................................802.5.1.12 Key words for MVS VSAM Files.................................................................................................802.5.1.13 Key words for Batch VSAM Files (VSE).....................................................................................802.5.1.14 Key words for SAM files (VSE)...................................................................................................822.5.1.15 Key words for DATACOM/DB....................................................................................................832.5.1.16 Key words for ADABAS...............................................................................................................842.5.1.17 Key words for EDN.......................................................................................................................87

January 2011

tcACCESS Version 8.0.0 Host Server

2.5.1.18 Keywords for CA-IDMS® records ..............................................................................................872.5.1.19 Key words for tcACCESS Virtual Disk........................................................................................922.5.1.20 Keywords for the Screen Content Server......................................................................................952.5.1.21 Keywords for the High Performance OST Server (Open System Transparency).........................972.5.1.22 Keywords for the tcACCESS ODBC-access................................................................................972.5.1.23 Keywords to access ORACLE (Open System Transparency).......................................................98

2.5.1.23.1 General...................................................................................................................................982.5.1.23.2 Supported database versions..................................................................................................982.5.1.23.3 Installation..............................................................................................................................982.5.1.23.4 Access types...........................................................................................................................99

2.5.1.24 Keywords to access DB2 UDB (Open System Transparency)....................................................1012.5.1.24.1 General.................................................................................................................................1012.5.1.24.2 Supported database versions................................................................................................1012.5.1.24.1 Installation............................................................................................................................1012.5.1.24.2 Access types.........................................................................................................................1012.5.1.24.3 Access to DB2 UDB-databases using the host API "TCAISRV"........................................1022.5.1.24.4 Access to DB2 UDB-databases using the host utility-program ‘TCASRVUP’..................102

2.5.2 Views....................................................................................................................................................1042.5.3 Exit Program for user specific data fields............................................................................................105

2.6 Stored Procedures........................................................................................................................................1072.6.1 Definition of a Stored Procedure:.........................................................................................................1072.6.2 Stored Procedures COMMAREA........................................................................................................1092.6.3 Special form of a Stored Procedure.....................................................................................................1102.6.4 Stored Procedure Example ..................................................................................................................1102.6.5 Stored Procedures defined using the GUI............................................................................................1112.6.6 Definition of a Stored Procedure with GUI.........................................................................................113

2.7 SQL Engine Security...................................................................................................................................1152.8 Technical Information.................................................................................................................................116

2.8.1 Catalog Functions.................................................................................................................................1162.8.1 Table Access Sequence .......................................................................................................................1182.8.2 Index controlled Access.......................................................................................................................1182.8.1 Index controlled access for GROUP BY and ORDER BY..................................................................120

2.8.1.1 Performance of ORDER BY and GROUP BY.............................................................................1202.9 User exit for data record processing............................................................................................................1212.10 User exit for SQL-Statements ...................................................................................................................122

3. Calling the tcACCESS Host Server from user written programs. ....................................................................1233.1 Calling the interface....................................................................................................................................124

3.1.1 CICS ....................................................................................................................................................1243.1.2 MVS or VSE Batch..............................................................................................................................125

3.2 Commands to call the Host Server Module................................................................................................1273.2.1 'DL' command.......................................................................................................................................1273.2.2 'SQ' command.......................................................................................................................................1283.2.3 'GN' command......................................................................................................................................1293.2.4 'TE' command......................................................................................................................................1303.2.5 'FR' command......................................................................................................................................1303.2.6 The Command 'TR'...............................................................................................................................1313.2.7 The Command 'TO'..............................................................................................................................131

3.2.7.1 Return codes of the interface.........................................................................................................1323.3 Calling the batch interface using 'TCASRVUP'.........................................................................................133

3.3.1 APOST................................................................................................................................................1343.3.2 CHECK ...............................................................................................................................................1343.3.3 CONNECT ..........................................................................................................................................1343.3.4 CSID.....................................................................................................................................................1343.3.5 DBL2CHAR.........................................................................................................................................1353.3.6 DECR ..................................................................................................................................................1353.3.7 DEF .....................................................................................................................................................1353.3.8 DESCRIBE...........................................................................................................................................135

January 2011


3.3.9 DOWNLOAD......................................................................................................................................1363.3.10 EXECSQL..........................................................................................................................................1373.3.11 EXIT .................................................................................................................................................1373.3.12 GEN DATALOAD.............................................................................................................................1373.3.13 GEN LOAD........................................................................................................................................1383.3.14 GOTO ...............................................................................................................................................1383.3.15 HOSTPARMS....................................................................................................................................1383.3.16 HOSTPARMS ADD..........................................................................................................................1383.3.17 IF .......................................................................................................................................................1393.3.18 INCR ................................................................................................................................................1393.3.19 MAXREC...........................................................................................................................................1393.3.20 MODULE...........................................................................................................................................1393.3.21 NULLS...............................................................................................................................................1403.3.22 NUM2ZONE......................................................................................................................................1403.3.23 NUMEDIT.........................................................................................................................................1403.3.24 ONERROR ........................................................................................................................................1413.3.25 OUTFILE...........................................................................................................................................1413.3.26 PARAMETER....................................................................................................................................1423.3.27 PUNCH..............................................................................................................................................1423.3.28 PAUSE ..............................................................................................................................................1423.3.29 TIMESTAMP ....................................................................................................................................1423.3.30 QUOTE.............................................................................................................................................1433.3.31 WAITC ..............................................................................................................................................1433.3.32 WTO ..................................................................................................................................................143

3.4 Access types of Server ″TCASOSTQ″........................................................................................................1443.4.1 Access using the tcACCESS SQL-Engine...........................................................................................1443.4.2 Access to the Server in an Online System............................................................................................1453.4.3 Direct access to the OST Server...........................................................................................................147

4. tcACCESS Virtual Disks...................................................................................................................................1494.1 tcACCESS Virtual Disks - Online Processing ...........................................................................................149

4.1.1 Partition Administration in an Online System......................................................................................1494.1.2 Command line in an Online System....................................................................................................151

4.2 tcACCESS Virtual Disks - Batch Utility Program......................................................................................1534.2.1 BACKUP ............................................................................................................................................1544.2.2 CD .......................................................................................................................................................1554.2.3 CONNECT ..........................................................................................................................................1564.2.4 COPY CON..........................................................................................................................................1564.2.5 DEL ....................................................................................................................................................1574.2.6 DIR ......................................................................................................................................................1574.2.7 FDISK ACTP.......................................................................................................................................1574.2.8 FDISK DELP.......................................................................................................................................1584.2.9 FDISK DIRP........................................................................................................................................1584.2.10 FDISK FORM....................................................................................................................................1594.2.11 FDISK FREP......................................................................................................................................1594.2.12 FDISK INAP......................................................................................................................................1604.2.13 FDISK UNDP....................................................................................................................................1604.2.14 FILE ..................................................................................................................................................1614.2.15 MD ....................................................................................................................................................1614.2.16 MODE ...............................................................................................................................................1614.2.17 PART .................................................................................................................................................1624.2.18 PWD ..................................................................................................................................................1624.2.19 RD .....................................................................................................................................................1624.2.20 RENAME ..........................................................................................................................................1624.2.21 RESET................................................................................................................................................1634.2.22 RESTORE .........................................................................................................................................1634.2.23 TYPE .................................................................................................................................................1644.2.24 TRUNCATE .....................................................................................................................................1644.2.25 USER .................................................................................................................................................164

4.3 Virtual Disks - Interfaces.............................................................................................................................166

January 2011


4.3.1 Commands for virtual disks..................................................................................................................1664.3.1.1 The 'ACTP' Command..................................................................................................................1674.3.1.2 The 'ASEC' Command...................................................................................................................1674.3.1.3 The 'CLOSE' Command................................................................................................................1684.3.1.4 The 'CREA' Command..................................................................................................................1684.3.1.5 The 'DELE' Command...................................................................................................................1684.3.1.6 The 'DELP' command....................................................................................................................1694.3.1.7 The 'DIRN' Command...................................................................................................................1694.3.1.8 The 'DIRP' Command....................................................................................................................1694.3.1.9 The 'DIRS' Command....................................................................................................................1704.3.1.10 The 'ECAS' Command.................................................................................................................1704.3.1.11 The 'FORM' Command...............................................................................................................1704.3.1.12 The 'FREE' Command.................................................................................................................1714.3.1.13 The 'FREP' Command.................................................................................................................1714.3.1.14 The 'INAP' Command.................................................................................................................1714.3.1.15 The 'INIT' Command...................................................................................................................1714.3.1.16 The 'MKDI' Command................................................................................................................1724.3.1.17 The 'LABL' Command................................................................................................................1734.3.1.18 The 'OPEN' Command................................................................................................................1734.3.1.19 The 'OPNR' command.................................................................................................................1734.3.1.20 The 'RDEA' Command................................................................................................................1734.3.1.21 The 'READ' Command................................................................................................................1744.3.1.22 The 'RELD' Command................................................................................................................1744.3.1.23 The 'RENA' Command................................................................................................................1744.3.1.24 The 'RESE' Command.................................................................................................................1754.3.1.25 The 'RMDI' Command................................................................................................................1754.3.1.26 The 'SET0', 'SET1' and 'SET2' Commands.................................................................................1754.3.1.27 The 'TERM' Command................................................................................................................1764.3.1.28 The 'TRON' command.................................................................................................................1764.3.1.29 The 'TROFF' command...............................................................................................................1764.3.1.30 The 'TSTU' Command.................................................................................................................1764.3.1.31 The 'UNDP' Command................................................................................................................1774.3.1.32 The 'WRIT' Command................................................................................................................1774.3.1.33 The 'WRTA' Command...............................................................................................................178

4.3.2 Calling Interfaces.................................................................................................................................1784.3.2.1 CICS..............................................................................................................................................1784.3.2.2 MVS or VSE Batch.......................................................................................................................179

5. Host Initiated Data Transfer..............................................................................................................................1815.1 Calling the Interface....................................................................................................................................181

5.1.1 CICS ....................................................................................................................................................1815.1.2 MVS or VSE Batch..............................................................................................................................182

5.2 Commands for a Host Initiated Data Transfer............................................................................................1835.2.1 The 'ST' Command...............................................................................................................................1835.2.2 The 'CA' Command .............................................................................................................................1835.2.3 The 'CO' Command..............................................................................................................................1845.2.4 The ‘TR’ Command.............................................................................................................................1845.2.5 The 'TO' command..............................................................................................................................1845.2.6 Interface Return codes..........................................................................................................................185

5.3 Call of a Host initiated Data Transfer via 'TCAH2PUP'.............................................................................1865.3.1 CHECK ...............................................................................................................................................1865.3.2 CONNECT ..........................................................................................................................................1875.3.3 DECR ..................................................................................................................................................1875.3.4 DEF .....................................................................................................................................................1875.3.5 EXIT ...................................................................................................................................................1875.3.6 GOTO .................................................................................................................................................1885.3.7 IF .........................................................................................................................................................1885.3.8 INCR ..................................................................................................................................................1885.3.9 ONERROR ..........................................................................................................................................1885.3.10 PAUSE ..............................................................................................................................................189

January 2011


5.3.11 PWD.............................................................................................................................................1895.3.12 PC-PARMS .......................................................................................................................................1905.3.13 PC-PARMS ADD .............................................................................................................................1905.3.14 PC-TIMEOUT ..................................................................................................................................1915.3.15 PC-WAIT ..........................................................................................................................................1915.3.16 START ..............................................................................................................................................1915.3.17 TIMESTAMP ....................................................................................................................................1915.3.18 USER..................................................................................................................................................1915.3.19 WAITC ..............................................................................................................................................1925.3.20 WTO ..................................................................................................................................................192

6. User specific Host Server..................................................................................................................................193

7. Index..................................................................................................................................................................194

January 2011


1. Host Server Modules

The host component of tcACCESS consists of a number of modules, which are to handle the data requests of the users. The various modules include components for the following tasks: Communication Managers, Basic Access Modules, SQL Engine, Virtual Disk, Logging and Security Manager.

The Communication Managers allow PC users to address the tcACCESS host components. In addition, the Communication Managers have the function to distribute user data requests to the respective access modules. This includes also the distribution to additional systems. Thus it is possible that a user connected to host A can access data on host B via an APPC interface.

The Basic Access Modules are programs, which provide direct access methods for certain data sources (e.g. read and write of VSAM records). The servers will be described in detail in a following section of this chapter.

The SQL Engine makes it possible to access non-SQL compatible data sources (e.g. VSAM, DL/I, etc.) by applying the SQL language. A detailed description can be found in chapter 2, page 10.

Virtual Disks provide the facility to prepare disk space on the host for PC clients in a way that this space can be accessed by the clients like any PC disk (e.g. DIR, CD, COPY, etc.). This function allows connecting PCs, which are not connected with each other via a network but have a connection with a host.

The data accesses of the users can be logged in a VSAM RRDS or DB2 or SQL/DS table. The following information is collected:• User identification• Processed function• Name of the PC client resource• Name of the host resource• Date• Time• Status • Number of sent records• Number of received records• Number of transmitted Bytes• Duration• Number of skipped records• CRC active• Transfer percentage display active

The Security Manager allows controlling or restricting data accesses of the users. tcACCESS includes an internal security system, which can handle this task. A PC application allows the administration of the user entries and the assignment of authorizations to them. Alternatively, the security may be handled by an external security manager (e.g. RACF). Then, before each data access, tcACCESS verifies, if the user is authorized for a function or a resource. Additional generation parameter can be used, to only display the resources to a user for which he has at least read authority.

In addition to the provided access modules special programs may be developed in order to integrate user specific data sources into the tcACCESS data access solution. These programs can also be applied for a complex data structure, which is difficult to address using the Basic Access Modules. This special data access logic is integrated into the tcACCESS solution in a user transparent mode.

January 2011


1.1 Basic Access Modules

The following list shows the functionalities, which are provided by the Basic Access Modules; the list is based upon the supported online system or data source.

MVS/VSE CICS and tcACCESS Monitor system:

• Read/write accesses to locally defined VSAM files• CICS: read/write accesses to remote defined VSAM files (files in FOR)• Directory functions for VSAM files with search key• Read/write accesses to TS queues• Directory functions for TS queues with search key• CICS: read accesses to TD queues• CICS: CEMT interface to process commands• Job Submit (RJE) to JES or POWER• MVS: Print into JES queues• VSE: Read/write accesses to POWER queues, including commands such as. 'PALTER ...'• VSE: Directory functions for POWER queues with search key

Data transfer from and to the host can be performed from a PC client in structured and/or selective format by using structure definitions.

Structured data transfer requires that the PC client software knows the structure of the host records. For this purpose the name, position, length and format of a field must be defined. Based on this structure information the user is in the position to save data in various output formats (e.g. dBase, CSV, etc.) in order to consecutively process this data, e.g. in a word document.

Selective data transfer allows applying logical conditions on all fields, which are downloaded. For instance it is possible to extract the customers of a certain area code from a customer file to download them. Using the PC front-end program the selection criteria can easily be defined. These selection criteria are transferred to the host; the selection criteria are applied against the host-file records and the defined fields of the selected records are downloaded to the PC.

DB2 Databases or VSE SQL/DS:

The SQL instructions submitted by a user are passed to DB2 or SQL/DS and the result is transferred to the PC. The user can view all accessible tables or 'Views' and by clicking on table or field names the required SQL statements created by the PC application.

MVS / OS/390 Files:

The access module for MVS permit read and write access to MVS PS/PDS files. The files are allocated using 'Dynamic Allocation' (SVC99) and deallocated again after the usage. The files can be overwritten; it is also possible to append data to already existing files (DISP=SHR or DISP=MOD). New files may be allocated (DISP=(NEW,CATLG)).

If a storage manager (e.g. DFHSM) is installed, a generation parameter is provided in order to control that MVS files are accessed by a separate internal task. This prevents a CICS wait when a file is migrated. Further the recall of migrated files can be avoided in general.

If another user processes an MVS file, the user id of this user will be returned.

It is also possible to search for MVS files by specifying the first qualifier and members in PDS files.

Further it is possible to perform a structured and/or selective data transfer from and to the host by applying structure definitions on the PC client.

January 2011


MVS QMF/IXF/DFT Files:

This module allows reading MVS PS/PDS files in IXF format (e.g. QMF, DXT, etc.). The data is returned in a result table format.

Batch VSAM Files:This module allows to access VSAM files with an entry in the VSE system standard label. Therefore, an FCT entry within CICS is not required. These VSAM files are accessed using their cluster name.

January 2011


2. SQL Engine

2.1 IntroductionThe SQL Engine allows access to non-SQL compatible data resources by using the SQL language.

Supported data sources:

CICS/VSE CICS/MVS tcACCESS Monitor system

DL/I DL/I DL/ICICS VSAM KSDS CICS VSAM KSDS CICS VSAM KSDSCICS VSAM ESDS CICS VSAM ESDS CICS VSAM ESDSCICS VSAM RRDS CICS VSAM RRDS CICS VSAM RRDSTS Queues TS Queues TS QueuesVSE SAM files MVS sequential and

partitioned filesMVS sequential and partitioned files

Batch VSAM KSDS MVS VSAM KSDS MVS VSAM KSDSBatch VSAM ESDS MVS VSAM ESDS MVS VSAM ESDSBatch VSAM RRDS MVS VSAM RRDS MVS VSAM RRDSDATACOM/DB DATACOM/DBADABAS ADABAS ADABAStcACCESS Virtual disks tcACCESS Virtual disks tcACCESS Virtual disksFile System EDN by Wilken GmbH

File System EDN by Wilken GmbH

CA-IDMS® databases CA-IDMS® databases CA-IDMS® databases

The SQL Engine can perform INSERT, UPDATE and DELETE SQL commands on the following data resources.

INSERT UPDATE DELETE

CICS VSAM KSDS CICS VSAM KSDS CICS VSAM KSDSCICS VSAM RRDS CICS VSAM RRDS CICS VSAM RRDSCICS VSAM ESDS CICS VSAM ESDSCICS TS Queue CICS TS Queue CICS TS Queue *ADABAS ADABAS ADABASDATACOM/DB DATACOM/DB DATACOM/DB DL/I DL/I DL/I EDN EDN EDN CA-IDMS® databases CA-IDMS® databases CA-IDMS® databases

* DELETE only possible without a WHERE condition.

January 2011


All supported data resources can be JOINed. The following table lists all functions and arithmetic operators that are supported.

Simple functions

● ABS() or. ABSVAL()● ACOS() ● ASIN() ● ATAN() ● ATAN2() ● ATANH() ● BIN() ● CEIL() or CEILING() ● CHAR() ● COALESCE() or VALUE()● CONCAT() ● CONNECTION_ID()● COS() ● COSH() ● CURRENT_TIMESTAMP() ● DATE() ● DAYOFMONTH() ● DAYOFWEEK() ● DAYOFWEEK_ISO() ● DAYOFYEAR() ● DAYS() ● DEC() or DECIMAL()● DECODE() ● DEGREES() ● DIGITS() ● DOUBLE(), DOUBLE_PRECISION() or

FLOAT()● EXP() ● FLOOR() ● HEX() ● HEXCHR() ● HOUR() ● IFNULL() ● INSERT() ● INT() or INTEGER()● JULIAN_DAY() ● LAST_DAY() ● LCASE() or LOWER() ● LEFT() ● LENGTH() ● LN() ● LOCATE() ● LOG() ● LOG10()

● LTRIM() ● MICROSECOND() ● MIDNIGHT_SECONDS() ● MINUTE() ● MOD() ● MONTH() ● NEXT_DAY() ● NULLIF() ● PI() ● POSSTR() ● POWER() ● QUARTER() ● RADIANS() ● RAND() ● REPEAT() ● REPLACE() ● RIGHT() ● ROUND() ● ROUND_TIMESTAMP() ● RTRIM() ● SECOND() ● SIGN() ● SIN() ● SINH() ● SPACE() ● SQRT() ● STR() ● STRIP() ● SUBSTR() ● TAN() ● TANH() ● TIME() ● TIMESTAMP() ● TRANSLATE() ● TRUNC() or TRUNCATE()● TRUNC_TIMESTAMP() ● UCASE() or UPPER()● USER()● VARCHAR() ● WEEK() ● WEEK_ISO() ● YEAR() ●

Group functions

● AVG()● COUNT()● MAX()● MIN()● SUM()● FIRST() ● LAST()

January 2011


Arithmetic Operators

● +● -● *● /● || or CONCAT

Compare operators

● <● >● =● >=● <=● <>● BETWEEN● LIKE● IN● IS NULL

Logical operators

● AND● OR

'Stored Procedure' support:

A CICS program or a tcACCESS Monitor System program can be used as a 'Stored Procedure'. It performs access operations on data sources, which are difficult to access using an SQL command. This allows processing of complex access logic against several data sources by using a program. A Stored Procedure eliminates the need to define a sequence of SQL commands for each individual access request. The client application calls this procedure and supplies the parameter. The program can access all resources which are available to the monitor system (CICS or the tcACCESS Monitor System).

SQL Engine control:

The SQL Engine uses the tcACCESS virtual disks for saving information about the available data sources, their field definitions and index access information. This information is stored in text files on the virtual disk. These files contain key words, which describe the record structures and the data resources. The file names always use an extension of FTB (e.g. TABLE.FTB).

Data defined in QMF/IXF format can be processed without a FTB definition. This data can be stored on TS Queues or MVS PDS/PS files.

Views of data structures can also be stored. They are SQL-SELECT statements, which have an extension of .VTB on the virtual disk. Views can be used to avoid users gaining global access to the original data sources or to present information from several data sources through a 'Join' in a tabular format. The data tables resulting from a 'View' can again be processed by the end user with SELECT statements. 'Views' may be applied to allow access to a certain section of a data source only.

As an example a 'View' can be used so that an end user only has access to data, which is related to his/her department:

SELECT T1.PERS_NO 'PERSONAL_NO', T2.PERS_NAM 'NAME', T1.PROJ 'PROJECT'

FROMPROJECTS T1, PERSONAL T2

WHERE

January 2011


T2.PERS_NO = T1.PERS_NO AND T2.DEPT = '37'

This SELECT statement provides information on all project team members but for department 37 only:

PERSONAL_NO NAME PROJECT... ... ...

Support of 'Outer Joins':

The following SELECT statement presents all NAMEs with the DEPartment they belong to. The value 'NULL' for the DEPartment will be assigned to NAMEs without a department specification.

SELECT T1.NAME, T2.DEP_NAMEFROM NAMES T1, DEP T2WHERE T2.DEP_NO (+) = T1.DEP_NO

The plus character (+) expands the department table with a NULL line, if no entry in the department table applies to the WHERE condition.

The following syntax is also supported:

table1 [INNER JOIN|LEFT OUTER JOIN |RIGHT OUTER JOIN] table2 ON join-condition

Support of 'GROUP BY' and 'ORDER BY':

The GROUP BY and ORDER BY key words are also supported together with the summarizing functions SUM(), MIN(), MAX(), AVG(),COUNT(), FIRST() and LAST().

SQL Engine Security:

The tcACCESS access verification is involved each time a table or view is accessed. If the data sources, which are referenced by the view, should be verified, the CRESEC parameter should be defined in the server module generation (see manual "tcACCESS Customization", chapter ' tcACCESS Server Modules generation', parameter 'CRESEC').

Usage of the SQL Engine:

The SQL Engine can be accessed from the tcACCESS front-end program by using the ODBC connection (Open Data Base Connectivity) or via various API interfaces available to an application program.

The data resulting from a query can be used in various ways.

• They may be stored in different formats such as ASCII, with delimiters (CSV), dBASE etc.• They may be imported into Excel and saved in a worksheet.• A customer address can be located by specifying the customer number; then the complete address can be

included into a word document, etc.• An application program on the PC may use the host as data server.

2.2 Activation and Administration

After the installation of the Server Modules in a CICS environment or the tcACCESS Monitor System, the programs, files and definitions needed by the SQL Engine are available on the host. One step of the host installation comprises the definition of the VSAM files. If the file for the virtual disk is defined, it will be initialized with the system tables, which are needed for the SQL Engine.

January 2011


2.2.1 System Entries

The VDISK generation parameter allows the specification of a virtual disk name. The SQL-Engine will search this disk for table definitions. The virtual disk expects to find information in the directory defined with the SUBDIR generation parameter (see manual "tcACCESS Customization", chapter ' tcACCESS Server Modules generation'). The SYSDINIT program initializes the virtual disk during the host installation by evaluating the supplied parameter:

...,PARM='SYSDSK TABLES'

If the default values ('TCAVDSK.SYSDSK' for VDISK and 'TABLES/' for SUBDIR) have been changed, the SYSDINIT program must be executed again with the customized parameter for the new defined VSAM file.

The SYSDINIT program copies four files into the SYSTEM subdirectory on the virtual disk:• SYSTAB.FTB• SYSCOL.FTB• SYSPROC.FTB• SYSPCOL.FTB

These files are needed by the tcACCESS front-end program and the ODBC connection for table and field queries.

2.2.1 User Entries

The definitions of the tables and 'Views' with the information about the data sources and their fields can be created with a PC text editor such as NOTEPAD.EXE or EDIT.COM. Next, the files must be copied into the directory of the virtual disk, which is defined in the SUBDIR generation parameter (default: TABLES/). If the files within the TABLES/ directories are stored into a subdirectory, this subdirectory name is used as a creator name (see '2.5 Tables and Views', page 63).

Notes:

Table- and field-names must only contain characters A-Z, 0-9, #, _ and $. All other characters are not supported.

Example:• Path to the FTB: TABLES/NORDWND/ARTICLE.FTB

⇒ SELECT instruction for article table: SELECT * FROM NORDWND.ARTICLE

If the files are stored into the TABLES/ directory, they are referenced without a creator specification.

Example:• Path to the FTB: TABLES/ARTICLE.FTB

⇒ SELECT instruction for article table: SELECT * FROM ARTICLE

January 2011


2.3 SQL Engine Commands and Statements

Each command and statement should be terminated with a semicolon ';'. Several statements separated from each other with a semicolon can be specified in one execution. A SELECT statement returning data rows interrupts the processing of the commands. Consecutive commands will be ignored.

2.3.1 Comments and Optional Statements

If a statement starts with '--', it is considered a comment.

However, there are a number of tcACCESS SQL Engine specific optional statements provided, which can be specified using the '--'.

There is only a single key word permitted per '-- ....;' command. It is necessary to take care that these "Comment lines" are also terminated with a semicolon.

If the host generation parameter OPTSEC=Y has been used and the tcACCESS security is active, it will be checked, whether the user has the authority to specify Options-definitions.

FROMTIME= Option

-- FROMTIME=hhmm;

This option specifies the time in hours and minutes for activating MAXIO and MAXROW options. The options will only be activated, if the current time is greater or identical to hhmm.

Example:-- FROMTIME=0900;-- MAXIO=10000;

INPUT_FILE= Option -- INPUT_FILE=file_name; This option specifies the name of the Host File, which is the input file for the subsequent query. Within the FTB the keyword '$DYNINPT' must be defined instead of the file name. The file_name must be a valid file name on the host. Example:

-- INPUT_FILE=TEST(TS);

KEEP_TBL_SEQ= Option

-- KEEP_TBL_SEQ=Y; This option controls the internal processing of JOINs in SQL queries by the tcACCESS SQL Engine. If the option specifies a 'Y' no optimization will occur. The sequence of table access will be performed as specified in the SQL statement. Example:

-- KEEP_TBL_SEQ=Y;

January 2011


KEYCHECK= Option -- KEYCHECK=(Y/N); This option controls the KEYCHECK function. If the parameter has been set to 'Y', the SQL-Engine will check whether the SELECT, UPDATE or DELETE-statements contain WHERE-clauses. If the WHERE-clauses only reference fields which are no key-fields, the statement will be rejected. SQL-statements with no WHERE-clause will not be objected to. If this option has not been specified the value of KEYCHECK used for the system generation will be used. Example: -- KEYCHECK=Y;

LIMIT= Option -- LIMIT=number; This option limits the number returned data lines in a result set for the query that follows the option. This option allows to only return the first n records of a result set. MAXCOL= Option -- MAXCOL=number; This option sets the maximum number of columns for the next statement. The SQL-Query will end abnormally, if the number of columns is greater than this number.

MAXIO= Option

-- MAXIO=number;

This option defines the maximum number of record accesses for the subsequent statements. If this statement is not defined, the number specified in the MAXIO generation parameter will be used.

MAXROW= Option

-- MAXROW=number;

This option defines the maximum number of returned data rows for the subsequent statements. If this statement is not defined, the number specified in the MAXROW generation parameter will be used.

NOORDERBY= Option

-- NOORDERBY=Y;

This option prohibits the usage of the ORDER BY key word in one of the following SQL statements. This will avoid sorting activities on the host. If ORDER BY is used in one of the consecutive SQL statements, the statement will terminate with an error message.

NOGROUPBY= Option

-- NOGROUPBY=Y;

This option prohibits the usage of the GROUP BY key word in one of the following SQL statements. This will avoid sorting activities on the host. If GROUP BY is used in one of the consecutive SQL statements; the statement will terminate with an error message.

OUTPUT_FILE= Option

January 2011


-- OUTPUT_FILE=filename;

This option specifies the name of the host file where the result of the query should be written. The PC client only receives the SQL return code.

Possible definitions for file_name:

Format Description Example fct_name VSAM file --OUTPUT_FILE=MYVSAM;queue_name(TS) TS Queue --OUTPUT_FILE=MYQUEUE(TS);dataset_name MVS PS/PDS file --OUTPUT_FILE=USER1.DATA(MEM);

The specified file name may contain the following variables. During execution the SQL Engine replaces them with the appropriate values:

Variable Description $$$T Terminal name$$$$$$$U User identification$$$$$$$N # (Hex.: 0x7B) + 7 digit CICS task number (Example: #0000040)

Using these variables one can define temporary user specific files, which can be used by subsequent statements.

OUTPUT_FORMAT= Option

-- OUTPUT_FORMAT=IXF;

Data should be written in QMF/IXF format.

The IXF parameter can only be used with the OUTPUT_FILE option.

Data in IXF format is written line by line and column by column.

OUTPUT_APPEND= Option

-- OUTPUT_APPEND=NO|YES;

This option specifies if data should be added to a host file or if an already existing file should be replaced. The default value is YES and appends the data at the end of a file.

This option is only valid with the OUTPUT_FILE option.

OUTPUT_NULL_INDICATOR= Option

-- OUTPUT_NULL_INDICATOR=YES|NO;

This option specifies if a two bytes NULL indicator prefix should be assigned to fields which are NULL. The indicator value of x'0000' indicates a non NULL field content.

The option is only valid with the OUTPUT_FILE option.

January 2011


STP_COMPAT Option

-- STP_COMPAT;

Stored Procedures can be called like in DB2. This requires the specification of all parameter, including output parameter. The input parameter are also part of the result set. You can activate this functionality when using option STP_COMPAT.

STR_DELIM= Option

-- STR_DELIM=Ö;

This option defines the delimiter for character strings. The default is the character ’ (quote).

SET_SQLID= Option

-- SET_SQLID=creatorname;

Using this option a standard value can be defined for the CREATOR (SQL-Id) in SQL-Engine queries. The creator-name specified in this option will always be used if no creator has been referenced in the SQL-statement. The setting of the SQL-Id defines a creator if an unqualified object has been referenced (Table, View, etc.) it has no implications on security.

If the SQL-Id has been set it is valid for the whole life-cycle of a host-connection. Subsequent use of -- SET_SQLID= overwrites the SQL-Id that was valid up and until this point.

Usage of the keyword $$USERID specifies the user-id of the currently signed on user.

This command must always be used in conjunction with an SQL-statement. If only the SQL-ID must be set, a dummy SQL-statement may be used that references table SYSTEM.SYSDUMMY1:

-- SET_SQL_ID =ADM01;SELECT * FROM SYSTEM.SYSDUMMY1;

The SQL-Id is valid for all objects of the SQL-Engine (Tables, Views, Stored-Procedures, Precompiled-Commands). Please note the following for precompiled SQL-statements (Precompiled-Commands): When saving a precompiled command with a specified SQLID this ID will be used during execution of the command independent of the currently active SQLID. It is not possible to reference precompiled commands unqualifiedly that are stored in a TS queue even if an SQLID has been set.

Examples:-- SET_SQLID=ADM01; ->Default-Creator is ADM01-- SET_SQLID=$$USERID; ->Default-Creator is ID of currently signed on user-- SET_SQLID=; ->Reset SQL-Id

2.3.1 The CALL Statement

The CALL statement calls a 'Stored Procedures' (see '2.1 Introducti', page 10); it has the following format:

CALL proc. name ( ) ; parameter ,

January 2011


Description:

procedure_name Defines the name of the Stored Procedure' which is called. The name consists of the creator name and the name of an STP object (*.STP file) stored on the virtual disk.

parameter One or several input values for the 'Stored Procedure'. The number and the format of the parameter must match with the 'Stored Procedure' definition (definition of IN or INOUT fields).

Example:

CALL TEST.TIMEPROC (1);

2.3.2 The COMMIT Statement

COMMIT

The COMMIT statement commits all changes since the beginning of this transaction or the specification of a NO-COMMIT statement. The COMMIT statements are activated for the data sources they are based upon. After processing of this statement is completed, the automatic COMMIT is activated again.

2.3.3 The DELETE Statement

DELETE FROM table view correlation ; WHERE search condition

The DELETE statement deletes rows (records) from the data source referenced to by the table-name or view- name.

Description:

table or viewDefinition of the table or 'view' name, which should be affected by the DELETE statement. It must be the name (creator.object) of an existing definition. Following objects must not be defined:• A table which does not allow deletion• A 'view' on such a table

correlation A correlation name can be defined. This name can then be used in the SEARCH condition of

the WHERE clause to reference the columns of the table or 'view'. WHERE search_condition

The SEARCH condition of the WHERE clause specifies the condition(s) to delete the rows of a table or a view. If it is omitted, all lines will be deleted.

The syntax described on page 23 applies for the search condition. It is applied on each single data line. If a row meets the condition, it will be deleted.

January 2011


2.3.1 The INSERT Statement

INSERT INTO table view ( column ) ,

VALUES( expression ) ; , subselect

The INSERT statement inserts one or several rows into the data source referenced by table- or view-name.

Description:

table or view This parameter allows to define the name of the table or 'view' for the insert operation. It must be the name (creator.object) of an existing definition. Following objects cannot be used:• A table which does not permit insertion• A 'view' on such a table• A 'view' which contains read-only columns. 'Read-only' columns are columns, which are

defined as constant, expression or function. If 'view' is specified, which contains 'Read-only' columns, a list of column names must be defined. None of these columns can be read-only.

column List of column names for which values to be inserted are specified. Each column must be unqualified. It identifies a column of a table or 'view'. The sequence is not important. Each column can only be defined once. 'Read only' columns of a view cannot be used.

If no column list is defined, all columns will be considered from left to right.

VALUES(expression,..)This parameter defines the values for the columns, which are to be inserted. The number of values must correspond with the defined columns. The first value is inserted into the first defined column the second value into the second column, etc. A detailed description for the specification of expressions can be found on page 30.

Subselect ... The data to be inserted my come from a different data resource. The subselect is used alternatively to the VALUES specification.

The number of columns resulting from the subselect must correspond with the defined columns. The first value of the first column of the result is inserted into the first defined column, the second value into the 2nd column, etc.

2.3.1 The NOCOMMIT Statement

NOCOMMIT

The NOCOMMIT statement deactivates the automatic COMMIT. It is the responsibility of a user to issue the appropriate COMMIT and ROLLBACK statements.

2.3.2 The ROLLBACK Statement

January 2011


ROLLBACK

The ROLLBACK statement dismisses all change operations, which have been performed since the beginning of this transaction or the definition of the NO-COMMIT statement. The related ROLLBACK statements are activated for the data sources they are based upon. After processing the statement the automatic COMMIT is activated again.

January 2011


2.3.3 The SELECT Statement

The SELECT statement consists of several clauses.

select-clause from-clause ( where-clause group by-clause having-clause

union-clause )

; order by-clause

Only one SELECT statement can be defined. If comments are to follow a SELECT statement, it must be terminated with a semicolon.

2.3.3.1 The SELECT Clause

The SELECT clause specifies the columns of the result table.

, SELECT expression DISTINCT column titel AS

*

name.*

Description:

DISTINCT DISTINCT removes – with the exception of one – all identical rows in a result table.

* The result table contains all columns of all tables which are defined in the FROM clause.

expression One or several constants or column names. If a column name is defined, it must be unique; otherwise the table name must prefix the column name. The definition of expressions is described in detail on page 30.

column_title A character string within quotes. This string will become the title of the column in the result table.

name.* The result table contains all columns of this table or 'view'. The name must be an existing table or 'view' defined in the FROM clause.

January 2011


2.3.3.2 The FROM Clause

, FROM table view correlation AS

The FROM clause defines the source of the result table.

Description:

table or view This parameter defines the name of the table or 'view' from which rows should be inserted into the result table. It must be the name (creator.object) of an existing definition (*.FTB or *.VTB definition).

correlation The correlation name can be used in consecutive clauses to reference to the columns of the specified table or 'view'.

During execution time, an internal temporary table is built from the data of the specified tables or 'views'. If a single table or 'view' is defined, the temporary table presents a copy of this table or 'view'.

If several tables or 'views' are defined, this temporary table consists of a composition including all rows of the defined tables or 'views'. Each row of the first defined table or 'view' is combined with each row of the second table or 'view'. This again is combined with each row of the third table or 'view' etc.. The number of rows within the internal temporary table is a composition of the number of rows of all defined tables or 'views'. If one of the tables or 'views' is empty, the temporary table is also empty.

2.3.3.3 The WHERE Clause

The WHERE clause determines the rows of the tables and views defined in the FROM clause which are to be included into the result table.

WHERE search condition

2.3.3.4 The EXIT_SET_WHEN Clause

The EXIT_SET_WHEN-clause specifies when the processing of the current result set will be terminated. If the condition becomes true the current row will be added to the result set and the the result set will be terminated like for an EOF condition.

EXIT_SET_WHEN search condition

2.3.3.5 The EXIT_ALL_WHEN Clause

The EXIT_ALL_WHEN-clause specifies when the processing of the current result set will be terminated and the processing of subsequent SQL commands in the SQL command-buffer is ignored. If the condition becomes true

January 2011


the current row will be added to the result set and the the result set will be terminated like for an EOF condition. In addition all remaining SQL commands in the SQL command-buffer will be ignored.

In case that the EXIT_ALL_WHEN-condition becomes true inside of a 'Stored procedure' using the GUI all subsequent SQL commands inside and outside of the 'Stored procedure' will be ignored.

EXIT_ALL_WHEN search condition

Search condition

The SEARCH condition is an expression, which may result in either 'true', or 'false'. Expressions can be combined to more complex expressions by using logical operators. If a SEARCH condition is 'true' for a row, this row will be passed to the result table. If the SEARCH condition for a row is 'false', this row will be rejected.

expression

(expression AND expression) OR

BOOLEAN operators for AND and OR:

A B A AND B A OR BTrue True True TrueTrue False False TrueFalse True False TrueFalse False False False

Comparison operators

A comparison expression compares two expressions.

expression = expression NOT <> (subselect) > < >= <=

Example: PERS_NAME = 'MUELLER ' AGE NOT >= 30

If any of the expressions is 'NULL', the result of the comparison is 'false'. If none of the expressions is 'NULL', the result can either be 'true' or 'false'.

A subselect must only contain one field or an expression and must only return a value or no value.

BETWEEN Operator

January 2011


expression1 BETWEEN expression2 AND expression3 NOT

The BETWEEN operator checks if expression 1 is greater or equal expression2 and smaller or equal expression3.

Example: Age BETWEEN 20 AND 23

The result is 'true' for age=20, age=21, age=22 and age=23.

If any of the expressions is 'NULL', the result of the BETWEEN operator is 'false'. If none of the expressions is 'NULL', the result can only be either 'true' or 'false'.

The EXISTS-Operator

EXISTS (Subselect) NOT

The result of the EXISTS is true, if the Subselect at least returns one line.

Example: SELECT * FROM DEMO.ARTICLE T1 WHERE EXISTS (SELECT * FROM DEMO.ARTICLE T2 WHERE T2.SUPPNR = T1.SUPPNR HAVING AVG(T2.PRICE) <= T1.PRICE)

LIKE-Operator:

expression LIKE sample NOT

The LIKE operator checks if the expression matches with the sample. Sample is a character string, which may contain the following characters:

• The percentage character % represents any character string in an optional length (also NO character).• The underscore '_' represents one optional character.• All other characters represent themselves.

Example:

Department LIKE ' %A_CD'

During the analysis of the LIKE clause, it is attempted to separate the value 'department' to build sub-character strings as follows:

• The first sub-character string contains none or an optional number of characters (% in sample).• The second sub-character string contains the character A (A in our sample).• The third sub-character string contains exactly one optional character (_ in our sample).• The fourth sub-character string contains the characters C and D (CD in our sample).

If this subdivision is successful, the result is 'true'.

The following values for 'Department' match with the sample:A B C D Y Z A B C D A B C A X C D2 3 4 1 2 3 4 1 2 3 4

January 2011


The following values for 'Department' do not match with the sample:A B X Y Z C D A X Y C D2 3 1 ? ? 1 2 ? ? ?

If any of the expressions is 'NULL', the result of the LIKE operator is 'false'. If none of the expressions is 'NULL', the result can either be 'true' or false'.

IN Operator:

, expression IN ( entry ) NOT (subselect)

The IN operator checks if expression exists in the list of entries.

Example:

Number IN (12, 34,56)

The result is 'true' for number=12, number=23 and number=56.

If any of the expressions is 'NULL', then the result of the IN operator is 'false'. If none of the expressions is 'NULL', the result can either be 'true' or 'false'.A Subselect must only contain one field or expression and may return any number of values.

NULL Operator:

expression IS NULL NOT

The NULL operator checks if the expression is NULL, i.e. it is not occupied.

If a numeric expression has the value '0' or a string expression contains an empty character string, then they are not equal to NULL because the value is ' ' or ""

Outer Joins:

An 'Outer Join' extends one of two defined tables or 'views' in a way that a NULL row is inserted when the 'Join' condition does not apply to any entry.

An 'Outer Join' is defined as follows:

column (+) = column

Example:

January 2011


SELECT T1.NAME, T2.DEPARTMENT_NAMEFROM EMPLOYEE T1, DEPARTMENTS T2WHERE T2.DEP_NO (+) = T1.DEP_NO;

This query displays the names of the employees and the department they belong to. Employees without a department assigned, get the department name NULL. Without the (+) extension these employees would not be included into the result table. The (+) extends the department table with a NULL row, if the search condition of the WHERE clause does not apply to it.

Another syntax for outer joins is:

+-INNER--------------------+ >>----table-------------------------------JOIN--table--ON--join-condition-----------> ¦ ¦ +-OUTER-+ ¦ ¦ ¦ +---LEFT---------------+ ¦ ¦ +-RIGHT-+ ¦ +-(--joined-table--)---------------------------------------------------+

Description:

table Name of the table or view for the JOIN

join-condition Name of the table or view for the JOIN

Example:

SELECT * FROM Q.PRODUCTS LEFT JOIN Q.PARTS ON Q.PARTS.PRODNO = Q.PRODUCTS.PRODNUM AND Q.PARTS.SUPPNO <> '1300S' LEFT JOIN Q.SALES

2.3.4 The GROUP BY Clause

, GROUP BY expression HAVING clause

The GROUP BY clause specifies a group of rows for which only a single result row (e.g. a summary row) should be created in the result table.

In each case all rows with identical values in the defined columns are combined to a group. The WHERE condition of the SELECT statement selects rows before the group is created. The HAVING clause selects the rows which are to be considered part of the group. For the group formation all NULL values are considered to be equal.

Description:

expression Definition of the rows belonging to the group. Only one row will be included into the result table for each group.

having-clause The HAVING clause specifies the condition(s) which must be met by the group.

2.3.4.1 The HAVING Clause

January 2011


The HAVING clause is defined in the same way as the WHERE clause (see '2.3.3.3 The WHERE Clause', page 23).

January 2011


2.3.5 The UNION clause

SELECT-statement UNION SELECT-statement ( ) ALL ( )

The ‘Union‘-clause combines the result-tables of 2 or more SELECT statements.

Description:

ALL Using this keyword, all rows of the SELECT will be returned. Without this keyword all multiple rows will be removed – with the exception of one row.

The column types must be combinable otherwise an error will be returned.

2.3.6 The ORDER BY Clause

, ORDER BY column number DESC

The 'ORDER BY' clause specifies the sequence of rows in the result table. The rows are first sorted in the order of the first column defined, then - if available - in with the order of a second column, etc.

Description:

column Column name(s) used for sorting.

number Column number(s) used for sorting.

DESC If this keyword is specified, the result table for this column will be sorted in descending order. If it is omitted, it will be sorted in ascending order.

The result of a SELECT statement with a 'GROUP BY' clause is already sorted according to the 'GROUP BY' arguments. An 'ORDER BY' clause is not necessary.

2.3.7 The UPDATE Statement

UPDATE table view correlation

SET column = expression , WHERE search condition

January 2011


The UPDATE statement will change the values of the defined columns and applies the changes to the corresponding data resource. Description:

table or view Name of table or 'view' whose rows are to be updated. It must be the name (creator.object) of an existing definition. The following objects must not be defined:• A table which does not permit updates• A 'view' on such a table• A 'view' which contains read-only columns. 'Read-only' columns are columns, which are

defined as constants, expressions or functions.

correlation The correlation name can be used in consecutive clauses to reference to the columns of the specified table or 'view'.

column = expressionThis parameter specifies the column(s) which is (are) to be updated. The columns must not be 'Read only'. It is not allowed, that one of the columns is part of the key.

WHERE search_conditionIf the WHERE clause is defined, it selects the rows to be updated. If it is omitted, all rows of a table or 'view' are updated.

The search condition is defined in the same way as for the WHERE clause of the SELECT statement (see '2.3.3.3 The WHERE Clause', page 23). The search condition is applied against each row of a table or 'view'. An update is performed for a row, if the result of the WHERE-clause is 'true'.

2.3.8 Expressions

Expressions can be defined as follows:

operator function - (expression) constant column-name

2.3.8.1 Operators

Operators allow to combine two expressions. The result is again an expression.

The following operators are supported:

|| Join of character strings/ Division* Multiplication+ Addition- Subtraction

2.3.8.2 Constants

A constant - also called literal - defines a value. Constants can be character strings and numeric values.

Example:

Numeric constants: 1 -4.34

January 2011


Character strings: 'Miller' 'SNOOPY'

2.3.8.3 The NULL Constant

The NULL constant is a special constant. It indicates that no value is assigned.

January 2011


2.3.9 SQL Functions

A function can be viewed as an operation which is specified by a function name and one or more arguments. The arguments must be enclosed within brackets.

Most of the functions contain a single argument only; it is defined as expression. The function will be applied on the result of the expression. The result of a function is a single value. Functions may result in a NULL value depending on the function arguments.

Whenever the term character string is used in the following chapter, this includes all field types whose internal representation is in characters (CHAR, VARCHAR, LONGVARCHAR, DATE, TIME, TIMESTAMP)

2.3.9.1 Single Functions

A single function processes one argument only and may be used where an expression is expected.

ABSVAL(expression)ABS(expression)

Description: The ABS-function returns the absolute value of the Expression, i.e. function ABS converts all negative values into positive values, positive values remain unchanged.

Expression-type: Numeric expression.

Result-type: Type of expression.

Example: ABS(123) 123ABS(-123) 123

ACOS(expression)

Description: The ACOS-function returns the Arcus Cosine of the Expression displayed as radian measure.


Result-type: FLOAT

Example: ACOS(0) 1.5707963267948E+00ACOS(-1) 3.1415926535897E+00

January 2011


ASIN(expression)

Description: The Asin- function returns the Arcus Sine of the Expression displayed as radian measure.


Result-type: FLOAT

Example: ASIN(0) 0ASIN(1) 1.5707963267948E+00

ATAN2(expression,expression)

Description: The ATAN2-function returns the Arcus Tangent of the numeric expressions displayed as radian measure.


Result-type: FLOAT

Example: ATAN2(1,1) 7.8539816334484E-01

ATANH(expression)

Description: The ATANH-function returns the hyperbolic Arcus Tangent of the expression displayed as radian measure.


Result-type: FLOAT

Example: ATANH(0.5) 5.4930614433405E-01

ATAN(expression)

Description: Die ATAN-function returns the Arcus Tangent of the numeric Expression displayed as radian measure.


Result-type: FLOAT

Example: ATAN(0.5) 4.6364760899806E-01

BIN(expression)

January 2011


The BIN function returns a character string with the binary representation of the argument. The result is a character string, which consists of the numbers '0' and '1'. The length of the character string is equivalent to the length of expression multiplied by eight. The maximum length of the result character string is 248. If the length of expression is greater than 31, the result is cut at the maximum length of 248.

CEILING(expression)CEIL(expression)

Description: The CEIL-function returns the smallest integer which is greater or equal to the supplied expression.


Result-type: Type of expression, no decimals

Example: CEIL(5.4) 6CEIL(-5.4) - -5

CHAR(expression,format)

Description: TheCHAR-function converts the defined value into a character string.

Expression-type: Any type.

Result-type: CHAR(n)

The type of conversion and the length of the character string will be defined by the type of the 1 st Expression and the defined format..

Type of expression Possible format definitions ResultCHAR Length n (n <= 256) CHAR(n)VARCHAR Length n (n <= 256) CHAR(n)INTEGER (4 bytes) CHAR(11)SMALLINT (2 bytes) CHAR(6)DECIMAL(p,s) Decimal point CHAR(p+2)FLOAT CHAR(23)TIMESTAMP CHAR(26)DATE ISO (yyyy-mm-dd)

USA (mm/dd/yyyy)EUR (dd.mm.yyyy)JIS (yyyy-mm-dd)

CHAR(10)

TIME ISO (hh.mm.ss)USA (hh:mm AM oder PM)EUR (hh.mm.ss)JIS (hh:mm:ss)

CHAR(8)

Example: CHAR('ABCDEF',3) 'ABC'CHAR(INT(5)) '5 'CHAR(5.4,',') ' 5,4'CHAR(PI()) '+.31415926535897933E+01'CHAR(DATE('2003-01-01'), EUR) '01.01.2003'CHAR(TIME('13.05.07',USA) '1:05 PM '

January 2011


COALESCE(expression[, expression[,expression...]])VALUE(expression [,expression [,expression...]])

Description: The COALESCE-function returns the first expression of the defined list which is not NULL.

Expression-type:all types; all expressions must be compatible to each other.

Result-type: Result of the combination of the Expression-types

Example: COALESCE('A','B','C') 'A'COALESCE(NULL,'B','C') 'B'

CONCAT(expression1, expression2)

Description: The CONCAT-function returns the concatenation of the two character string expressions

Expression-type: CHAR, VARCHAR

Result-type: CHAR, if both Expressions are CHAR; VARCHAR, if one of the expressions is VARCHAR. The length will be the sum of both individual lengths.

Example: CONCAT('A','B' ) 'AB'

COS(expression)

Description: The COS-function returns the Cosine of the expression displayed as radian meadsure.


Result-type: FLOAT

Example: COS(1) 5.4030230586813E-01

COSH(expression)

Description: The COSH-function returns the hyperbolic Cosine of the expression displayed as radiuan measure.


Result-type: FLOAT

Example: COSH(1) 1.5430806348152E+00

CURRENT_TIMESTAMP()

January 2011


The CURRENT_TIMESTAMP function returns the current host time.

Result-type:TIMESTAMP

Example: CURRENT_TIMESTAMP() ’2007-02-25-14.13.47.567823’

DATE(expression)

The DATE function returns the date of expression.

Expression-type:TIMESTAMP, numeric expression or character stringA numeric expression is considered as number of days counted from January, 1st of the base year, which has been specified during system generation (default is 1800). The 01.01.MINYEAR is day number 1. In order to use a character string as an expression it must have the format 'yy-mm-dd'

Result-type:DATE

Example: DATE(74140) ’2002-12-25’.

DAYOFMONTH(expression)

Description: The DAYOFMONTH- function returns the day of the month of the defined date -argument.

Expression-type:TIMESTAMP, DATE or character string.A character string as expression must be in format 'yyyy-mm-dd' or 'yyyy-mm-dd.hh.mi.ss.micsec'.

Result-type: INTEGER

Example: DAYOFMONTH('2002-12-25') 25

January 2011


DAYOFWEEK(expression,style)DAYOFWEEK_ISO(expression)

Description: The DAYOFWEEK- function returns the day of the week for the defined date-Expression.

Expression-type:TIMESTAMP, DATE or character string.A character string as expression must be in format 'yyyy-mm-dd' or 'yyyy-mm-dd.hh.mi.ss.micsec'.The DAYOFWEEK- function allows the definition of a week-starting day as an additional Expression (1: ISO = Monday; 2: USA = Sunday). If this definition is omitted the style as defined in the tcACCESS system-generation will be used (refer to DOWSTYL).Function DAYOFWEEK_ISO always returns the working day relative to Monday.


Example: DAYOFWEEK('2002-12-25',1) 3 (Wednesday)

DAYOFYEAR(expression)

Description: The DAYOFYEAR- function returns the actual calendar day of the year defined in the date-expression.

Expression-type:TIMESTAMP, DATE or character string.C


Example: DAYOFYEAR('2002-12-25') 359DAYOFYEAR('2003-01-01') 1

DAYS(date)

The DAYS function returns the number of days from January, 1st of the base year defined in the system generation (default 1800) until the specified date.

Argument-type:TIMESTAMP, DATE or character string. The Date argument must be a value in the date format or a character string of format'yyyy-mm-dd' or ’yyyy-mm-dd.hh.mi.ss.micsec’.

Result-type:DECIMAL(7)

Examples: DAYS(‘1999-01-01‘) 72686DATE(DAYS(‘2001-04-03‘) + 30) ’2001-05-03’

January 2011


DECIMAL(expression, positions [,fractions] [,decimal point])DEC(expression, positions [,fractions] [,decimal point])

The DECIMAL function returns the decimal presentation of a numeric value.

Expression-type:The expression must consist of a numeric value or character string, which can be converted to a numeric value. The specification for positions must be a value between 1 and 27 (inclusive). The specification for fractions must be a value between 0 and 27 (inclusive). If a fraction specification is omitted, '0' is assumed.

Result-type:DECIMAL(positions,fractions)

For the interpretation of character string decimal point can be used to specify the character that is used to identify the fractions. If omitted, the decimal point will be used.

Example:DECIMAL(‘123456‘,8,2) 123456.00DECIMAL(‘1234.56‘,8,2) 001234.56DECIMAL(‘1234,56‘,8,3,‘,‘) 01234.560

DECODE(expression, search1, result1, [search2, result2...], default)

It will be searched for the expression in the specified criteria search1, search2, ... and the result result1, result2, ... will be returned. If the expression is not found, the value defined for the default will be returned. If the expression is NULL, it will be searched for a searchn = NULL and the respective result will be determined.

Expression-type:any type, the search criteria must be compatible.

Result-type:Type of result1.

Example:DECODE(’0041’,‘0049‘,‘GERMANY‘,‘0033‘,‘FRANCE‘, ‘N/A‘) ‘N/A‘

DEGREES(expression)

Description: The DEGREES- function recalculates the expression from radian measure to degree.

Expression-type:Numerical expression.

Result-type: FLOAT

Example: DEGREES(PI()) 180

January 2011


DIGITS(expression)

Description: The DIGITS- function returns a character string consisting of the digits of the defined numeric expression.

Expression-type:INTEGER or DECIMAL

Result-type: CHAR(n)The length of the character string will be:

DECIMAL(p,s) pINTEGER 10SMALLINT 5

Example: DIGITS(123.456) '123456'DIGITS(INT(1)) '0000000001'

DOUBLE_PRECISION(expression)DOUBLE(expression)FLOAT(expression)

Description: This function converts the defined expression into FLOAT.

Expression-type:numeric expression

Result-type: FLOAT

Example: FLOAT(1) 1.000000E+00

EXP(expression)

Description: The EXP- function returns base ε raised to a higher power with the defined number as expression. The constant ε is base of the natural logarithm and has a value of 2,7182818284590433

Expression-type:Numeric expression.

Result-type: FLOAT

Example: EXP(1) 2.7182818284590E+00

January 2011


FLOOR(expression)

Description: The FLOOR-function returns the largest integer which is less or equal to the defined expression.


Result-type: Type of expression, no decials

Example: FLOOR(5.4) 5FLOOR(-5.4) - -6

HEXCHR(expression)

Description: The HEXCHR-function translates the defined expression into a character string. The defined expression will be treated like a hexadecimal value.

Expression-type:Character string consisting of '0' - '9' and 'A' bis 'F'.

Result-type: CHAR(n).The length of the character string is half of the length of the defined expression.

Example: HEXCHR('F1F2F3') '123'

HEX(expression)

The HEX function returns the hexadecimal representation of the expression in form of a character string. The length of the result is based on the length of expression multiplied by two. The maximum length is 254. If the length of expression exceeds 127, the result will be cut at position 254.

Expression-type:character string, consisting of ‘0’ - ‘9’ and ‘A’ - ‘F’.

Result-type:CHAR(n).The length of the character string is half the length of expression .

Example: HEXCHR(‘F1F2F3’) ‘123’

HOUR(expression)

Description: The HOUR-function returns the hours of the defined time-expression.

January 2011


Expression-type:TIMESTAMP, TIME or character string.A character string as expression must be in format 'yyyy-mm-dd' or 'yyyy-mm-dd.hh.mi.ss.micsec'.


Example: HOUR('14.13.47') 14

IFNULL(expression1, expression2)

Description: The IFNULL-function returns the first expression of the defined expressions, which is not NULL.

Expression-type:any type; the expressions must be compatible to each other.

Result-type: The combination of expression types

Example: IFNULL('A','B') 'A'IFNULL(NULL,'B') 'B'

INSERT(source, p, n, insertion)

Description: The INSERT-function returns a character string, whereas n characters will be deleted in SOURCE as of position p and will be replaced with INSERTION.

Expression-type:SOURCE and INSERTION must be character strings; p and n must be numeric expressions.

Result-type: CHAR(n)

Example: INSERT('tcACCESS', 6, 1, '<->') 'tcACC<->SS'

INTEGER(expression)INT(expression)

Description: The INTEGER-function returns the integer value of the expression.



Example: INT(14.13) 14

January 2011


JULIAN_DAY(expression)

Description: The JULIAN_DAY-function returns the number of days of the defined date starting from January 1st, 4713 BC.



Example: JULIAN_DAY('2002-12-25') 2452634

LCASE(expression) LOWER(expression)

Description: The LCASE-function returns the specified character string in lower case characters. The

translation from upper- to lower-case characters can be controlled by the generation macro TCAVDUCT (refer to manual "tcACCESS Customization ")

Expression-type:character string.

Result-type: equal to expression

Example: LCASE('tcACCESS') 'tcaccess'

LAST_DAY(expression)

Description: The LAST_DAY-function returns a date with the last day of the month of the specified date-expression

Expression-type:TIMESTAMP, DATE or character stringA character string as expression must be in format 'yyyy-mm-dd' or 'yyyy-mm-dd.hh.mi.ss.micsec'.

Result-type: DATE

Example: LAST_DAY('2002-12-25') '2002-12-31'

LEFT(expression,length[,OCTETS|CHARACTERS])

Description: The LEFT-function returns the first characters defined by length of the specified expression. The optional third argument defines the length as either number of bytes or number of characters. The default value is CHARACTERS character fields and OCTETS for all other field types.

Expression-type:

January 2011


Expression-type:Expression must be a character string; Length must be a numeric expression

Result-type: VARCHAR

Example: LEFT('tcACCESS',3) 'tcA'

LENGTH(expression[,OCTETS|CHARACTERS])

Description: The LENGTH-function returns the actual length of the defined character string expression. The optional third argument defines the length as either number of bytes or number of characters. The default value is CHARACTERS character fields and OCTETS for all other field types.

Expression-type:Character string


Example: LENGTH('tcACCESS') 8

LN(expression)LOG(expression)

Description: The LN-function returns the natural logarithm of the expression.


Result-type: FLOAT

Example: LN(100) 4.6051701859880E+00

LOG10(expression)

Description: The LOG10-function returns the base-10 logarithm of the argument.


Result-type: FLOAT

Example: LOG10(100) 2

January 2011


LOCATE(needle,haystack[,start][,OCTETS|CHARACTERS])

Description: The LOCATE-function returns the position of needle in haystack. The search starts at start. If start is not defined, the search will start at position 1. If needle will not be found, a 0 (zero) will be returned. The optional third argument defines the length as either number of bytes or number of characters. The default value is CHARACTERS character fields and OCTETS for all other field types.

Expression-type: needle and haystack must be character strings; start must be a numeric expression


Example: LOCATE('ACCESS','tcACCESS') 3LOCATE('ACCESS','tcACCESS',8) 0

LTRIM(expression)

Description: The LTRIM-function returns the specified expression without leading spaces.



Example: LTRIM(' tcACCESS') 'tcACCESS'

MINUTE(expression)

Description: The MINUTE-function returns the minutes of the specified time-expression.



Example: MINUTE('14.13.47') 13

January 2011


MIDNIGHT_SECONDS(expression)

Description: The MIDNIGHT_SECONDS-function returns the seconds of the specified time-expression since midnight.



Example: MIDNIGHT_SECONDS('14.13.47') 51227

MOD(dividend,divisor)

Description: The MOD-function returns the remainder of the devision of dividend by divisor.

Expression-type:divisor and dividend must be numeric expressions.

Result-type: FLOAT, if expression is FLOAT.INTEGER, if both arguments are INTEGER.Other combinations: DECIMAL

Example: MOD(10,3) 1

MONTH(expression)

Description: The MONTH-function returns the month of the year of the specified date expression.



Example: MONTH('2002-12-25') 12

MICROSECOND(expression)

Description: The MICROSECOND-function returns the micro seconds of the specified time expression.

Expression-type TIMESTAMP, TIME or character stringt.A character string as expression must be in format 'yyyy-mm-dd' or 'yyyy-mm-dd.hh.mi.ss.micsec'.


Example: MICROSECOND('14.13.47') 0MICROSECOND('2003-12-25.14.13.47.767645') 767645

January 2011


NEXT_DAY(expression,weekday)

Description: The NEXT_DAY-function returns the date of the next weekday after the specified date expression.

Expression-type:TIMESTAMP, DATE or character string.A character string as expression must be in format 'yyyy-mm-dd' or 'yyyy-mm-dd.hh.mi.ss.micsec'.WEEKDAY can be one of the following:- MON Monday- TUE Tuesday- WED Wednesday- THU Thursday- FRI Friday- SAT Saturday- SUN Sunday

Result-type: DATE

Example: NEXT_DAY('2002-12-25','SAT') '2002-12-28'

NULLIF(expression1,expression2)

Description: The NULLIF-function returns NULL, when expression1 and expression2 are identical.

Expression-type:expression1 and expression2 must have compatible types.

Result-type: Type of expression1.

Example: NULLIF('A','A') NULL

January 2011


PI()

Description: The PI-function returns the value of π.

Result-type: FLOAT

Example: PI() 3.1415926535897E+00

POSSTR(haystack,needle)

Description: The POSSTR-function returns the position of needle in haystack. The search starts at 1. If needle is not found, a 0 (zero) will be returned.

Argument-type: needle and haystack must be character strings.


Example: POSSTR('tcACCESS','ACCESS') 3

POWER(m,n)

Description: The POWER-function raises number m to the nth power.

Argument-type: m and n must be numeric expressions.

Result-type: INTEGER, if both arguments are INTEGER otherwise FLOAT.

Example: POWER(10,2) 100

QUARTER(expression)

Description: The QUARTER-function returns the quarter of the year specified in the date-expression.



Example: QUARTER('2003-12-25') 4

January 2011


RADIANS(expression)

Description: The RADIANS-function converts the expression from degrees to radians.

Argument-type:Numeric expression.

Result-type: FLOAT

Example: RADIANS(180) 3.1415926535897E+00 ( PI() )

RAND(seed)

Description: The RAND-function returns a random value between 0 and 1. The calculation can be influenced by the seed.


Result-type: FLOAT

Example: RAND(0) 0.65838718414306641

REPEAT(source,number)

Description: The REPEAT-function returns a character string, which consists of number of concatenated source character strings.

Argument-type: source must be a character string, number must be a numeric expression.

Result-type: VARCHARIf source and number are constant the result length will be LENGTH(source) * number.If one of the expressions is not a constant, the length will be 4000.

Example: REPEAT('abc',3) 'abcabcabc'

REPLACE(source,search,new)

Description: The REPLACE-function returns a character string, where all occurrences of search in source have been replaced with new.

Argument-type: Character strings.


Example: REPLACE('tcACCESS','ACCESS','EXPRESS') 'tcEXPRESS'

January 2011


RIGHT(expression,length[,OCTETS|CHARACTERS])

Description: The RIGHT-function returns the right-most characters in the length of length of the specified expression. The optional third argument defines the length as either number of bytes or number of characters. The default value is CHARACTERS character fields and OCTETS for all other field types.

Argument-type: expression must be a character string; length must be a numeric expression


Example: RIGHT('tcACCESS',6) 'ACCESS'

ROUND(expression,n)

Description: The ROUND-function returns the expression rounded up to n decimal digits. If n < 0, expression is rounded to the absolute value of number+1 number of places to the left of the decimal point.


Result-type: like expression; if expression is DECIMAL, length will be incremented by 1.

Example: ROUND(123.4567,2) 123.4600ROUND(123.4567,0) 123.0000ROUND(123.4567,-2) 100.0000

ROUND_TIMESTAMP(expression[,format])

Description: The ROUND_TIMESTAMP-function returns the specified expression rounded by the specified format. If format has not been specified, rounding to the day takes place.


Result-type: TIMESTAMP

Format Description Example 1 Example 2CC Century,

Rounding starts with year 50'1999-12-25-14.13.17.564324'↓'2000-01-01-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2000-01-01-00.00.00.000000'

YYYYYEARYYYYYYIYYYIYYIYI

Year,Rounding starts with July 1st

'2002-04-25-14.13.17.564324'↓'2002-01-01-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2003-01-01-00.00.00.000000'

January 2011


Q Quarter,Rounding starts with the 16th

day of the 2nd month

'2003-01-25-14.13.17.564324'↓'2003-01-01-00.00.00.000000'

'2003-02-25-14.13.17.564324'↓'2003-04-01-00.00.00.000000'

MONTHMONMMRM

Month,Rounding starts with 16th day

'2002-12-15-14.13.17.564324'↓'2002-12-01-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2003-01-01-00.00.00.000000'

WW Weekday of January 1st ,Rounding starts at 12 o'clock at the 3rd day of the week

'2000-12-25-14.13.17.564324'↓'2000-12-23-00.00.00.000000'

'2000-12-28-14.13.17.564324'↓'2000-12-30-00.00.00.000000'

IW Weekday of January 1st,Rounding starts at 12 o'clock at the 3rd day of the week; Weekday-calculation based upon ISO

'2000-12-25-14.13.17.564324'↓'2000-12-25-00.00.00.000000'

'2000-12-28-14.13.17.564324'↓'2001-01-01-00.00.00.000000'

W Weekday of the 1st day of the month,Rounding starts at 12 o'clock at the 3rd day of the week

'2002-12-24-14.13.17.564324'↓'2002-12-22-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2002-12-29-00.00.00.000000'

DDDDDJ

Day,Rounding starts at 12 o'clock

'2002-12-25-11.13.17.564324'↓'2002-12-25-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2002-12-26-00.00.00.000000'

DAYDYD

Weekday,Rounding on Tuesday at 12 o'clock;1st weekday is Sunday

'2002-12-24-11.13.17.564324'↓'2002-12-22-00.00.00.000000'

'2002-12-24-12.13.17.564324'↓'2002-12-29-00.00.00.000000'

HHHH12HH24

Hour,Rounding as of 30 minutes

'2002-12-25-14.13.17.564324'↓'2002-12-25-14.00.00.000000'

'2002-12-25-14.33.17.564324'↓'2002-12-25-15.00.00.000000'

MI Minute,Rounding as of 30 seconds

'2002-12-25-14.13.17.564324'↓'2002-12-25-14.13.00.000000'

'2002-12-25-14.13.37.564324'↓'2002-12-25-15.14.00.000000'

SS Seconds,Rounding as of 500000 Milli-seconds

'2002-12-25-14.13.17.064324'↓'2002-12-25-14.13.17.000000'

'2002-12-25-14.13.17.564324'↓'2002-12-25-14.13.18.000000'

RTRIM(expression)

Description: The RTRIM-function returns the specified expression without trailing spaces.



Example: RTRIM('tcACCESS ') 'tcACCESS'

January 2011


SECOND(expression)

Description: The SECOND-function returns the seconds of the specified time expression.



Example: SECOND('14.13.47') 47

SIGN(expression)

Description: The SIGN-function returns the sign of the specified expression:-1 for values < 0 0 for values = 0+1 for values > 0

Expression-type:Numeric expression

Result-type: Type of expression; if expression is decimal and length corresponds to decimal places, length will be incremented by 1.

Example: SIGN(-7) -1

SIN(expression)

Description: The SIN-function returns the sine of the expression displayed as radian.


Result-type: FLOAT

Example: SIN(1) 8.4147098480789E-01

SINH(expression)

Description: The SINH-function returns the hyperbolic sine of the expression displayed as radian.


Result-type: FLOAT

Example: SINH(1) 5.2109530549374E-01

January 2011


SPACE(n)

Description: The SPACE-function returns a character string with n spaces.

Argument-type: Numeric value.

Result-type: VARCHAR(n)

Example: SPACE(4) ' '

SQRT(expression)

Description: The SQRT-function returns the square roor of the specified expression.

Expression-type:Numeric value.

Result-type: FLOAT

Example: SQRT(9) 3.000000E+00

STRIP(expression[,where[,what]])

Description: The STRIP-function returns a character string. Depending upon where, leading or trailing characters for what have been deleted in expression. Possible values for where:

- B or BOTH leading and trailing where-characters will be deleted.- L or LEADING leading where-characters will be deleted.- T or TRAILING trailing where-characters will be deleted.

If where has not been specified, BOTH will be assumed.If what has not been specified, a space character will be assumed.

Expression-type:expression must be a character string.


Example: STRIP(' tcACCESS ') 'tcACCESS'STRIP(' tcACCESS ',T) ' tcACCESS'STRIP('OTTO',,'O') 'TT'

STR(number, positions [,fractions] [,sign] [,decimal point])

The STR function returns the presentation of a numeric value in form of a character string.

Argument-type:The number must be a numeric expression. Positions specify a value between 1 and 27 (inclusive). Fractions specify a value between 0 and 27 (inclusive). If the specification for fractions is omitted, '0' is assumed.

January 2011


Result-type:CHAR

If sign was specified as 'N', no sign will be used. If sign was specified as 'Y' or has been omitted, the number is presented with a (+, -) sign.

Decimal point specifies the character to indicate fractions. If omitted the period (.) will be used.

Example: STR(123.45,7,2) ’+00123.45’STR(123.45,7,2,N) ’00123.45’STR(123.45,7,2,,’,’) ’+00123,45’

SUBSTR(character_string, start [,length][,OCTETS|CHARACTERS])

The SUBSTR function returns a part of character string beginning with Start position in the length defined. If the length is not specified, the rest of character string, beginning with start position is returned. The specifications for start and - if used - length must be numeric constants.The optional fourth argument defines the length as either number of bytes or number of characters. The default value is CHARACTERS character fields and OCTETS for all other field types.

Argument-type:A character string must not exceed 255 positions.

Result-type:CHAR

Example: SUBSTR(’tcACCESS’,3,2) ’AC’SUBSTR(’tcACCESS’,3) ’ACCCESS’

TAN(expression)

Description: The TAN-function returns the Tangent of the expression dispalyed as radian.


Result-type: FLOAT

Example: TAN(1) 1.5574077246549E+00

TANH(expression)

Description: The TANH-function returns the hyperbolic Tangent of the expression displayed as radian.


Result-type: FLOAT

Example: TANH(1) 7.6159415595576E-01

January 2011


TRANSLATE(source[,to[,from[,pad char]]])

Description: The TRANSLATE-function searches every single character in source for from. If found, it will be replaced with to at the same position. If to contains less characters than from, pad char will be used. If no pad char has been specified, a space character will be used. If from has not been specified, source will be converted into upper case characters.If to has not been specified, a character string with a length of 256 and a content of x'00' to x'FF' will be assumed.

Argument-type: Character strings

Result-type: Type like source.

Example: TRANSLATE('tcACCESS','12','ABC') 'tc1 ESS

TRUNCATE(expression,n)TRUNC(expression,n)

Description: The TRUNCATE-function truncates the defined expression to the specified decimal places (n).


Result-type: Type like expression

Example: TRUNCATE(123.4567,2) 123.4500TRUNCATE(123.4567,0) 123.0000TRUNCATE(123.4567,-2) 100.0000

TRUNCATE_TIMESTAMP(expression[,format])

Description: The TRUNCATE_TIMESTAMP-function returns the specified expression rounded down by the specified format. If format has not been specified, rounding down to the day takes place.


Result-type: TIMESTAMP

Format Description Example 1 Example 2CC Century '1999-12-25-14.13.17.564324'

↓'2000-01-01-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2000-01-01-00.00.00.000000'

YYYYYEARYYYYYYIYYYIYYIYI

Year '2002-04-25-14.13.17.564324'↓'2002-01-01-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2002-01-01-00.00.00.000000'

January 2011


Q Quarter '2003-01-25-14.13.17.564324'↓'2003-01-01-00.00.00.000000'

'2003-02-25-14.13.17.564324'↓'2003-01-01-00.00.00.000000'

MONTHMONMMRM

Month '2002-12-15-14.13.17.564324'↓'2002-12-01-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2002-12-01-00.00.00.000000'

WW Weekday of January 1st '2000-12-25-14.13.17.564324'↓'2000-12-23-00.00.00.000000'

'2000-12-28-14.13.17.564324'↓'2000-12-23-00.00.00.000000'

IW Weekday of January 1st, weekday calculation based upon ISO

'2000-12-25-14.13.17.564324'↓'2000-12-25-00.00.00.000000'

'2000-12-28-14.13.17.564324'↓'2000-12-25-00.00.00.000000'

W Weekday of the 1st day of the month

'2002-12-24-14.13.17.564324'↓'2002-12-22-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2002-12-22-00.00.00.000000'

DDDDDJ

Day '2002-12-25-11.13.17.564324'↓'2002-12-25-00.00.00.000000'

'2002-12-25-14.13.17.564324'↓'2002-12-25-00.00.00.000000'

DAYDYD

Weekday,1st day of week is Sunday

'2002-12-24-11.13.17.564324'↓'2002-12-22-00.00.00.000000'

'2002-12-24-12.13.17.564324'↓'2002-12-22-00.00.00.000000'

HHHH12HH24

Hour '2002-12-25-14.13.17.564324'↓'2002-12-25-14.00.00.000000'

'2002-12-25-14.33.17.564324'↓'2002-12-25-14.00.00.000000'

MI Minute '2002-12-25-14.13.17.564324'↓'2002-12-25-14.13.00.000000'

'2002-12-25-14.13.37.564324'↓'2002-12-25-14.13.00.000000'

SS Seconds '2002-12-25-14.13.17.064324'↓'2002-12-25-14.13.17.000000'

'2002-12-25-14.13.17.564324'↓'2002-12-25-14.13.17.000000'

TIME(expression)

The TIME function determines a time value (type TIME) based on the defined expression.

Expression-type:TIMESTAMP, TIME or a convertible character string (Format ‘hh.mm.ss‘).

Example:TIME('17.33.20')

TIMESTAMP(expression)

The TIMESTAMP function determines a value of the 'timestamp' type based upon the defined expression.

Expression-type:TIMESTAMP, DATE or a convertible character string (Format ‘yyyy-mm-dd‘ or ‘yyyy-mm-dd-hh.mi.ss‘ or ‘yyyy-mm-dd-hh.mi.ss.milsec‘).

Example:TIMESTAMP('1998-11-2') TIMESTAMP('1998-11-2-12.33.20')

January 2011


UPPER(expression) UCASE(expression)

The Upper function translates the specified expression to upper case characters. The translation can be controlled using the system generation parameter TCAVDUCT (refer to manual ‚tcACCESS Customization')

Argument-type:character string

Result-typelike expression

Example: UPPER(‘tcACCESS‘) 'TCACCESS'

USER()

The USER function returns the 8-digit character string with the current user identification.

Result-type:CHAR(8)

Example: USER() ‘CICSUSER‘

VARCHAR(expression,format)

Description: The VARCHAR- function converts the specified value into a character string.

Expression-type: Any type.

Result-type: VARCHAR(n)

The type of conversion and the length of the character string is based upon the type of the expression and the specified format.

Type of expression Possible format specifications ResultCHAR Length n (n <= 256) VARCHAR(n)VARCHAR Length n (n <= 256) VARCHAR(n)INTEGER (4 Byte) VARCHAR(11)SMALLINT (2 Byte) VARCHAR(6)DECIMAL(p,s) Decimal-point VARCHAR(p+2)FLOAT VARCHAR(23)TIMESTAMP VARCHAR(26)DATE ISO (yyyy-mm-dd)

USA (mm/dd/yyyy)EUR (dd.mm.yyyy)JIS (yyyy-mm-dd)

VARCHAR(10)

TIME ISO (hh.mm.ss)USA (hh:mm AM or PM)EUR (hh.mm.ss)

VARCHAR(8)

January 2011


JIS (hh:mm:ss)

Example: VARCHAR('ABCDEF',3) 'ABC'VARCHAR(INT(5)) '5 'VARCHAR(5.4,',') ' 5,4'VARCHAR(PI()) '+.31415926535897933E+01'VARCHAR(DATE('2003-01-01'), EUR) '01.01.2003'VARCHAR(TIME('13.05.07'),USA) '1:05 PM '

WEEK(expression)

Description: The WEEK-function returns the actual calendar week of the specified date expression.

Expression-type: TIMESTAMP, DATE or character string.A character string as expression must be in format 'yyyy-mm-dd' or 'yyyy-mm-dd.hh.mi.ss.micsec'.


Example: WEEK('1999-01-01') 1

WEEK_ISO(expression)

Description: The WEEK_ISO-function returns the actual calendar week of the specified date expression in ISO-format. The first week of a year is the one which at least contains 4 days of the year. A week containing less than 4 days of the year is considered to be part of the previous year.



Example: WEEK_ISO('1999-01-01') 53

YEAR(expression)

Description: The YEAR-function returns the year of the specified date expression.



Example: YEAR('2002-12-25') 2002

January 2011


2.3.9.2 Grouping Functions

The following explanations are valid for all grouping functions, with the exception of the COUNT(*) version of the COUNT function:

The argument of a grouping function consists of a sequence of values determined on the base of one or several columns. The grouping functions internally perform a 'GROUP BY' function.

The argument of a grouping function must contain a column name. It must not include any grouping functions. Grouping functions can also be specified in the WHERE clause in order to select a certain group.

AVG([DISTINCT]expression)

The AVG function returns the average value of a numeric group.

The values resulting from expression must be numeric. The sum of these values must be in the permissible range for their respective data type.

The function is applied on the values resulting from expression; NULL values are not considered.

The data type of the result is determined by the values, which result from expression. Exception: The result of an AVG function with 'smallint' values belongs to 'largeint' type.

If the group is empty, NULL is returned.

Using keyword DISTINCT only different values in the group will be considered for the calculation.

COUNT([DISTINCT]expression)

The COUNT function determines the number of rows within a group which does not contain NULL for expression.

The result belongs to type 'integer' and can not be NULL.


COUNT(*)

This special form of the COUNT function determines the number of all rows within a group.

MAX([DISTINCT]expression)

The MAX function determines the maximum range of expression including all rows of the group.

The function is applied on values resulting from expression without considering NULL values.

The data type of the result is determined by the values resulting from expression.

If the group is empty, NULL is returned.Using keyword DISTINCT only different values in the group will be considered for the calculation.

January 2011


MIN([DISTINCT]expression)

The MIN function determines the minimum range of expression including all rows of the group.

The function is applied on values resulting from expression without considering NULL values.

The data type of the result is determined by the values resulting from expression.



SUM([DISTINCT]expression)

The SUM function returns the sum of all numerical values within a group.

The values resulting from expression must be numeric. The sum of these values must be in the permissible range for their respective data type.

The function is applied on the values resulting from expression; NULL values are not considered.

The data type of the result is determined by the values resulting from expression. Exception: The result of a SUM function with 'smallint' values belong to the 'largeint' type.



FIRST(expression)

The First function returns the value of expression when creating the group. If expression is a field of a table, the returned value is the field value of the first record in the group.

The data type of the result is based upon the resulting value of expression. NULL will be returned, if the group was empty.

LAST(expression)

The Last function returns the value, which was determined last. If expression is a field of a table, the returned value is the field value of the last record in the group.

The data type of the result is based upon the resulting value of expression. NULL will be returned, if the group was empty.

January 2011


2.4 Precompiled SQL-Statements The precompilation allows the timely separation of the compilation and execution of an SQL-statement.

Depending upon the complexity of the SQL-statement the compilation of the statement and the preparation of the index- and structure-information might be costly. The precompilation only performs this task once and the compiled object can be executed multiple times afterwards. This will drastically reduce the execution time, especially those where the part of the compilation is significantly larger than the execution of the request.

During compile the prepared statement can be stored on the Virtual Disk (permanent storage), in a TS-Queue (temporary storage) or in main storage (temporary storage within a transaction).

At execution time only the compiled output will be read and the execution will be stared using the supplied parameter.

Precompilation is supported for the following SQL-statements:SELECTUPDATEINSERTDELETE

2.4.1 The Precompilation

The PRECOMP_NAME= Option

--PRECOMP_NAME=name;

This option specifies the name and the type of the host file which should be used to store the compile output of the SQL-statements following this option.

Possible specifications for name:

Format Description Example MAIN Main storage --PRECOMP_NAME=MAIN;queuename(TS) TS-Queue --PRECOMP_NAM=MYCMD(TS);filename Virtual Disk --PRECOMP_NAME=PRECOMP.MYCMD;

Output to Main Storage:The output will be written to main storage and will be available until the next COMMIT (also AUTOCOMMIT) or ROLLBACK. Multiple outputs to main overwrite each other.

Example:--PRECOMP_NAME=MAIN;INSERT INTO TEST.ARTICLE VALUES(?,?);EXECUTE MAIN ('value1','value2');EXECUTE MAIN ('value3','value4');

--PRECOMP_NAME=MAIN;INSERT INTO TEST.SUPPLR VALUES(?);EXECUTE MAIN ('value1');EXECUTE MAIN ('value2');

Output into TS-Queue:The output will be saved into a TS-queue and will be available until the next start of the CICS or the tcACESS VTAM-Monitor System. Multiple outputs to the same TS-file overwrite each other.

Example:--PRECOMP_NAME=MYCMD1(TS);INSERT INTO TEST.ARTICLE VALUES(?,?);--PRECOMP_NAME=MYCMD2(TS);

January 2011


INSERT INTO TEST.SUPPLR VALUES(?);EXECUTE MYCMD1 ('value1','value2');EXECUTE MYCMD1 ('value3','value4');EXECUTE MYCMD2 ('value1');EXECUTE MYCMD2 ('value2');

Output to Virtual Disk:The output will be written to a file on the Virtual Disk owned by the SQL-Engine (TABLES-directory). The output will be permanently available. Multiple outputs to the same file name overwrite each other.

The name consists of the Creator and the name of a CTB-Objects (suffix *.CTB) on the Virtual Disk of the SQL-Engine. The Creator (directory on the Virtual Disk) must be created in advance.

Example:--PRECOMP_NAME=PRECOMP.MYCMD1;INSERT INTO TEST.ARTICLE VALUES(?,?);--PRECOMP_NAME=PRECOMP.MYCMD2;INSERT INTO TEST.SUPPLR VALUES(?);EXECUTE PRECOMP.MYCMD1 ('value1','value2');EXECUTE PRECOMP.MYCMD1 ('value3','value4');EXECUTE PRECOMP.MYCMD2 ('value1');EXECUTE PRECOMP.MYCMD2 ('value2');

The parameter

All expressions of the SQL-statement, which should be replaced with the actual values during execution time, must be specified with "?"-place holders. Refer to the above examples.

The LOAD_PRECOMP= option

--LOAD_PRECOMP=name;

This option copies a precompiled SQL-statement from Virtual Disk into main storage.

Possible specifications for name:

Format Description Example filename Virtual Disk --LOAD_PRECOMP=PRECOMP.MYCMD;

The precompiled statement can then be executed using EXECUTE MAIN (...).

The LOAD_PRECOMP= option Should be used for precompiled SQL-statements which will be executed multiple times. Multiple accesses to the Virtual Disk will be eliminated.

January 2011


2.4.2 The execution using EXECUTE

The EXECUTE-statement executes a compiled SQL-statement and has the following format:

EXECUTE name ( ) ; parameter ,

Description:

name Specifies the name of the precompiled SQL-statement to be executed. The name is different depending upon the location of the compiled output.:

Main storage:The name is ‚MAIN'

TS-Queue:The name of the TS-queue.

Virtual DiskThe name consists of the Creator and the name of a CTB-Objects (a *.CTB file) of the Virtual Disk owned by the SQL-engine.

parameter One or more input values for the precompiled SQL-statement. The number and the format of the parameter must match the "?"-placeholders of the precompiled SQL-statement.

Example:

EXECUTE PRECOMP.MYCMD1 (1, 'ddd');EXECUTE MAIN (1, 'ddd');EXECUTE TSCMD (1, 'ddd');

January 2011


2.5 Tables and Views Definition

The description of the table with the data sources it is based upon and their fields, as well as the description of the 'views', can be defined and maintained by using a PC ASCII editor (e.g. NOTEPAD.EXE). The extension for files with the table's description is FTB; for 'views' it is VTB . To activate the definitions, the files are copied to the virtual disk, which is used as the data dictionary by the SQL Engine. The virtual disk and the directory are defined in the VDISK and SUBDIR parameter during the generation of the Server Modules. The default value is TABLES=TCAVDSK.SYSDSK and SUBDIR=TABLES. Within the directory defined by SUBDIR another directory is created. The data is copied into it. This subdirectory name is the name of the creator of the table or 'view'.

Example:\TABLES\GROUP1\TABLE.FTB

This table is accessed with SELECT * FROM GROUP1.TABLE

2.5.1 Table Definition

A line starting with '*' is treated as comment. On all other lines a key word followed by one or several arguments or parameter is expected. All arguments or parameter of a key word must be on a single line; they must not be separated by CR/LF.

There are two types of key words: the global key words and the special key words, which are valid for a particular data source.

2.5.1.1 Key word HOSTFILE=

HOSTFILE=name[(type)]

The key word HOSTFILE= specifies the data source the table is based upon. It designates the name and the type of the data source.

In the name component of the data source variables may be used. These variables are replaced with the actual values during execution time.

Variable Description $$$T Terminal name$$$$$$$U User identification$$$$$$$N # (Hex.: 0x7B) + 7 digit CICS task number (Example: #0000040)

This variable allows to access user specific data sources.

Example:In the following example a TS queue is defined for the data source. Its name consists of the current user identification:

HOSTFILE=$$$$$$$U(TS)

January 2011


2.5.1.2 Key word FIELD=

The key word FIELD= specifies the individual fields of a host data resource record.

FIELD=name,use-flag,host_type,pc_type,position,length,decimal,subtype,adabas-namemax-number,tab-entry-length,maxno-field,index-field,ccsid,stp-gui expression

Description:

name SQL Engine internal name for this field. When used with SQL statements this represents the column name.

use-flag Only fields which are specified with 'Y' are processed. For 'Stored procedures' defined with the GUI input parameter are defined with 'I', output parameter are defined with 'O' and input/output parameter are defined with a value of 'P' .

host_type Data type of fields within the host data source. The following values are possible:• C EBCDIC characters in COBOL PIC X(xx)• L Memo field EBCDIC characters (length > 255 bytes)

with a leading length field (2 bytes)• M Memo field EBCDIC characters (length > 255 bytes)

without length field• X Bytes (Output is hexadecimal representation)

in COBOL PIC X(xx)• P packed numbers in COBOL PIC 9(xx) COMP-3• Z packed numbers with sign in COBOL PIC S9(xx)• H Half word in COBOL PIC 9(4) COMP

see subtype for a detailed definition• F Full word in COBOL PIC 9(8) COMP

see subtype for a detailed definition• D Date 'YYYY-MM-DD'

see subtype for a detailed definition• S Timestamp 'YYYY-MM-DD-HH.MM.SS.TTTTTT'

see subtype for a detailed definition• T Time 'HH-MM-SS'

see subtype for a detailed definition

pc_type Type of field on the PC client. This field is currently not used; it should be specified 'C' for character strings and 'N' for numeric fields.

position Position of the field within the record of the data source. If '-1' is defined, the position of the current field will be calculated based on the position of the previous field and its length.If the data source is an Adabas database, this value determines the position of the SQL Engine field within the field name which is defined for adabas-name.

length Length of the field within the host record. This parameter is not necessary for fields with a fixed length, such as e.g. type 'H', 'F' or 'D'. For fields of the type 'C' this parameter determines the length of the character string. A character string must not exceed 255 positions. For fields of type 'P' and 'Z' this parameter determines the total number of numerals (not the physical length).

decimal For fields of type 'P' and 'Z' this value determines the fractions.

subtype Subtype can represent a user defined datatype. These datatypes can be created using macro TCADCONV or using a field exit. Numbers up to 128 are reserved for tcACCESS internal datatypes.

January 2011


This parameter specifies the host_type of the field in more details. When the field is interpreted, both the host_type as well as subtype fields are considered. The subtype is defined as a number.

Value H Type Source Format Length0 D character 'YYYY-MM-DD' 10 Bytes, length must be 10.1 D packed YYDDD length byte, minimum 3.

length must be defined.2 H binary 1 Byte Integer

without sign1 Byte, length is ignored.

3 F binary 3 Bytes Integer without sign

3 Bytes, length is ignored.

50 D binary YYYYMMDD 4 Bytes, length must be 4.51 D character 'YYMMDD' 6 Bytes, length must be 6.52 D binary YYYYYYYMMM

MDDDDD2 Bytes, length must be 2.

54 D character 'YYYY.MM.DD' 10 Bytes, length must be 10.55 D character 'YYYYMMDD' 8 Bytes, length must be 8.56 D Full word 'DDDDDDDD' 4 Bytes, length must be 4.57 D packed ADABAS Date 4 Bytes, length must be 4.80 S packed ADABAS

Timestamp 7 Bytes, length must be 7.

90 T packed ADABAS time 7 Bytes, length must be 7.100 Z,P,H,F Numeric value,

controlled signAccording to definition

101 Z,P,H,F Numeric value, always positive

According to definition

Numeric value with following sign1

PIC 9(n) → n+1

If user specific field types must be processed, the field exit program must be implemented and customized (see '2.5.3 Exit Program for user specific data fields', page 106). The subtype may then be a value >= 128. User specific date conversions can be performed using macro “TCADCONV“. They are evaluated before a field exit is called. Detailed information about macro TCADCONV can be found in manual "tcACCESS customization parameter" .

Adabas-name 2-digit name of the field within the database while using ADABAS as data source. For details see 'ADABAS Command Reference Manual', chapter 'Format Buffer'.

Virtual tables – Virtual tables represent the resolution of the entries of a tables, that is part of the data-record, to multiple "virtual" data-records. Every virtual data-record represents a table entry. The following fields define this.

max-numberl If virtual tables are to be used, this field contains the maximum number of table entries in a data-record.

1 In COBOL or IDMS this type of numerics can be defined as "SIGN IS TRAILING SEPARATE CHARACTER".

January 2011


tab-entry-length If virtual tables are to be used, this field contains the length of a table entry. If a table entry consists of multiple fields, the combined length of the table entry must be specified here and the field length itself must be set to 0 (ZERO). Next all fields of the table must be defined. For ADABAS this field is always NULL or empty. For nested tables, the index fields of these tables must be included as well.

maxno-field If the number of table entries of virtual tables depends upon a field (OCCURS … DEPENDING ON …), the field name can be specified that contains the number of table entries.

index-field For every table entry a data-record is constructed. This data-record may contain the position of the table entry in this index-field. The field defines the name of the index field that belongs to the table. The index field MUST be defined immediately BEFORE the table-entry and must be a half word.

The following field is only relevant when the Global Language Pack has been installed.

ccsid This entry specifies the CCSID that applies to the field in the datasource.

The following field is relevant, when a 'Stored Procedure' has been defined using the GUI.

stp-gui expression This field contains a SQL-expression, whose result will be written into the corresponding COMMAREA-field. The SQL-expression may contain constants and references to the calling parameter. Refer to chapter Fehler: Referenz nicht gefunden, Fehler: Referenz nicht gefunden.

At runtime tcACCESS verifies, that the data of the host source match with the respective field definition. In case of an error (e.g. unpacked data, invalid format for date field) the SQL Engine assigns NULL. NULL is also assigned when a host record is shorter than the defined field position and field length. Whereas, character strings are filled with blanks as soon as they are longer than the host record defined.Example for field definitions:

* Field- Host PC Posi- Length Dec. Sub- * name: type type tion type* -------------------------------------------------------------------FIELD=Fld_half word, Y, H, N, 0, FIELD=Fld_full word, Y, F, N, 2, FIELD=Fld_packed Y, P, N, -1, 7, 2,FIELD=Fld_sign_zoned, Y, Z, N, -1, 7, 2,FIELD=Fld_character, Y, C, C, -1, 10, FIELD=Fld_date, Y, D, C, -1, 4, , 1FIELD=Fld_timestamp, Y, D, C, 316, 10,FIELD=Fld_one_byte, Y, H, N, -1, , , 2FIELD=Fld_three_bytes, Y, F, N, -1, , , 2

January 2011


2.5.1.3 Key word STRUCTURE=

STRUCTURE= [ IXF | FTB(ftb-file name) ]

This key word allows to call a field definition from another FTB file. If this key word is applied, it is not necessary to define FIELD= keywords. The STRUCTURE= key word must be the last key word of an FTB file.

Description:

IXF The host file is saved in IBM/IXF format. This format describes the individual data in a type of header. The data sources for such data are TS Queues or MVS PDS/PS.

FTB(ftb-file name)ftb-file name is the name of the file on a virtual disk which contains the field definitions. The file must be stored on the same virtual disk where the current FTB file is also located. It may reside in another directory. The full path must be specified.e.g. STRUCTURE=FTB(/DIRFTB/FIELDS.TXT)

2.5.1.4 Key word RECEXIT= RECEXIT=program_name

If this key word is specified, the defined program will be called after each record read- and before each write-operation. This program is required, for example, when records are stored in a compressed format. A description of the parameter for this program can be found in chapter 2.8 'User exit for Record Processing', of the Host Server Manual.

2.5.1.5 Key word INSERT_INITIALIZE= INSERT_INITIALIZE=[YES|NO]

A definition of "YES" for this keyword initializes the fields prior to an INSERT based upon their field type. Numeric fields will be set to (zero) character fields will be initialized to BLANKS.

2.5.1.6 Key words for TS Queues

Definition of data source:

HOSTFILE=queue-name(TS)

Special keywords:

DELTSQ=[ Y | N ]

If this parameter is set to 'Y' the TS-queue is automatically deleted after the SELECT-statement. This can be desirable, when a TS-queue should only be used temporarily (i.e. created with –OUTPUT_FILE= or by a Stored Procedure) and should not remain in the system.

January 2011


Examples:

HOSTFILE=MYQUEUE(TS) DELTSQ=Yor

HOSTFILE=WRQ1$$$T(TS) STRUCTURE=IXF

January 2011


2.5.1.7 Keywords for TD-Queues


HOSTFILE=queue-name(TD)

Example:

HOSTFILE=CSKL(TD)

Note: Only an INSERT can be performed into a TD-queue.

2.5.1.8 Key words for VSAM Files


HOSTFILE=fct-file-name

This allows to access VSAM files which are defined within CICS or the tcACCESS Monitor system.

Special key words:

STARTKEY=path1,path2,pathn...STARTKEY_UNIQUE=path1,path2,pathn... STARTKEY_NONUNIQUE=path1,path2,pathn...

It is possible to define alternative indexes for VSAM KDSD and EDSD clusters. They are automatically used depending on the specified SQL statements. The specifications must be the VSAM path entries which are assigned to the base file.

The usage of STARTKEY_UNIQUE= or STARTKEY_NONUNIQUE= instead of STARTKEY= defines this additional index, the SQL-engine can use them to determine the indexes of a table using SYSTEM.SYSIDX.

KSDS_KEYLEN=length of key...KSDS_KEYPOS=position of key...

VSAM files can be defined remote within CICS; they are located in another CICS region (FOR). Since tcACCESS always tries to figure out the most efficient access path, it is necessary to call a program within the FOR (program name: TCAVSINQ) to get these information for the remote files.

Using these parameter,you can define all the information needed to access the remotely defined CICS VSAM KDSD files. In this case no program will be called in the FOR.

January 2011


Examples:

HOSTFILE=MYVSAMor

HOSTFILE=MYVSAMSTARTKEY=PATH1,PATH2

orHOSTFILE=MYVSAMKSDS_KEYLEN=30 KSDS_KEYPOS=0

Special field for VSAM/RRDS-filesThe definition of a field with a name of ‘RRDS_RRN’ supports the direct access to a data record using the relative record number. The SQL-Engine automatically uses this field as a unique key-field. The fields must be defined with a typeof FULLWORD and must be the first field in the FTB definition with an offset of 0. Only if this field is available a VSAM/RRDS file can be changed (INSERT, UPDATE, DELETE).

2.5.1.9 Keywords for DL/I Segments

Definition of the data source:

HOSTFILE=psb-name(DL/I)

Special key words:

STARTKEY=PCB=n,SSA=ssa1,SSA=ssa2,SSA=ssan...STARTKEY_UNIQUE=PCB=n,SSA=ssa1,SSA=ssa2,SSA=ssan... STARTKEY_NONUNIQUE=PCB=n,SSA=ssa1,SSA=ssa2,SSA=ssan...

For each index of an IMS segment a STARTKEY= key word can be specified. The SQL-engine automatically decides what index to be used, depending upon the definitions in the SQL-statement.


PCB=n specifies the PCB which is to be used within the PSB. PCB=0 is the first PCB.

SSA=... allows to specify the SSAs which must be used. It is possible to define up to eight SAAs in the following format:

SSA=segment-name (key-name>=FIELDS(key-field[,key-field]))

The FIELDS() statement specifies the names of the FIELD= entries which make up the complete key.

The SQL Engine always returns the segment name and the complete key-feedback area. For this reason it is necessary to define the segment field and the key-feedback area (see examples).

The following restrictions must be considered:

• As DL/I does not allow to use more than one PSB at a time, all PCBs within a query must refer to one PSB.

January 2011


• Each of these segments must relate to different PCBs within this PSB, to be able to save the individual positions in a database.

• Each segment used in a query must have its own PCB.

Examples:

HOSTFILE=PSBM653(DL/I)STARTKEY=PCB=0,SSA=ASRO (ASROA01K>=FIELDS(KA01,KR28))*FIELD=SEGMENT, Y, C, C, 0, 8, 0FIELD=KA01, Y, P, N, -1, 13, 0FIELD=KR28, Y, P, N, -1, 3,FIELD=A01, Y, P, N, 17, 13, 0FIELD=R28, Y, P, N, 24, 3,FIELD=L01, Y, C, C, 32, 25,

HOSTFILE=DL/IPSB(DL/I)STARTKEY=SSA=ASRO (ASROA01K>=FIELDS(A_A01,A_R28)), SSA=ALIF (ALIFA10K>=FIELDS(A_A10,A_R51))**SEGMENT NAMEFIELD=SEGMENT, Y, C, C, 0, 8, 0*KEY FEEDBACK AREAFIELD=A_A01, Y, P, N, -1, 13, 0FIELD=A_R28, Y, P, N, -1, 3,FIELD=A_A10, Y, P, N, -1, 5,FIELD=A_R51, Y, C, C, -1, 1,*SEGMENT FIELDSFIELD=A10, Y, P, N, -1, 5,FIELD=R51, Y, C, C, -1, 1,FIELD=A07, Y, P, N, -1, 7,

SEGMENT_DATA=nnn

Through the specification of multiple indexes the length of the key feedback area can vary. This keyword specifies the start of the actual data portion in the created record. The free are in front of that position can be used for multiple key feed back areas for the specified indexes. If this definition has been omitted or the specified value is too small, the starting position of the segment data is controlled by the longest key feedback area. Using this keyword allows the addition or removal of indexes in a FTB without having to change the start of the data fields.

January 2011


Example:

HOSTFILE=PSBM653(DLI)STARTKEY=PCB=0,SSA=ASRO (ASROA01K>=FIELDS(KA01,KR28))STARTKEY=PCB=0,SSA=ASRO (ASROA02K>=FIELDS(KL01))SEGMENT_DATA=100*FIELD=SEGMENT, Y, C, C, 0, 8, 0*FIELD=KA01, Y, P, N, 8, 13, 0FIELD=KR28, Y, P, N, -1, 3,*FIELD=KL01, Y, C, C, 8, 25,*FIELD=A01, Y, P, N, 100, 13, 0FIELD=R28, Y, P, N, -1, 3,FIELD=L01, Y, C, C, -1, 25,

Example based on the structure of a complete database:

The database of this example contains the following segments:

VEMOID

VEAREA

VECOMI

...

...

The VEMOID segment is the root segment; the VEAREA and VECOMI segments are on a lower level within the hierarchy. The root segment is defined as follows:

January 2011


* DBD NAME=SVEPDBS,ACCESS=xxxx DATASET DD1=SVEPDBS,DEVICE=nnn,BLOCK=nnn,SCAN=n* SEGM NAME=VEMOID,PARENT=0,BYTES=140,PTR=TB*

Further segments are defined, as the following example shows:

* SEGM NAME=VEAREA,PARENT=VEMOID,BYTES=130 ...* SEGM NAME=VECOMI,PARENT=VEAREA,BYTES=nnn ...*

Access to the root segment:

First, the VEMOID segment must be accessed. For an unqualified access to the segment it is only necessary to define the segment name in the program.

* 01 UNQUAL-VECNTRL-SSA PIC X(09) VALUE 'VEMOID '. *

For tcACCESS, the data source related parameter for the SQL Engine look as follows:

STARTKEY=PCB=0,SSA=VEMOID .

The SSA specification is passed to DL/I. Therefore, it is necessary to comply with the syntax for SSAs. For this unqualified access, the segment name is assumed as a 10 character value. If it is shorter, the remaining positions will be filled with blanks followed by a dot. A syntax error will be recognized by the DL/I error message 'AJ' during the access.

For a qualified access to a segment, the separation of fields and keys is defined within Cobol. Later in this chapter, this example also explains the definitions of the VEMOID root segment and the VEAREA segment. The keys of the segments are shown in italics.

* 01 VEMOID PIC X(140) VALUE SPACES. 01 VEMOID-FIL REDEFINES VEMOID. 02 VEAMOID PIC X(21). 02 FILLER REDEFINES VEAMOID. 05 VEASOCI PIC X(02). 05 VEAMODE PIC X(07). 05 VEAFILL PIC X(12). * Data fields ... 02 VEADESC PIC X(15). 02 VEATIAR PIC X(01). 02 VEAUNMI PIC X(02). 02 VEAALIQ PIC X(02). ...

January 2011


*

The key can appear in two different ways as it is shown in the picture below. To access the segment, both unqualified and qualified (e.g. for a JOIN), you should define two FTBs. Let's have a separate look at each section..

VEAMOID - PIC X(21)

VEASOCIPIC X(02)

VEAMODEPIC X(07)

VEAFILLPIC X(12)

When importing the segment structure from a copy-book, you should notice, that the actual data area is prefixed with the 8-digit-segment name and the key-feedback area. In our VEMOID example the actual data area starts at position 29.( 8+21=29 bytes). Always define these two fields during the import. The following FTB should result from the import:

** SQL Engine definition file (FTB format)*HOSTFILE=SVEPDBS(DL/I) <- PSB definitionSTARTKEY=PCB=0,SSA=VEMOID (VEAMOID >=FIELDS(K_VEAMOID)) <- see below** ! field ! used ! host ! pc ! start ! length ! scale ! user * ! name ! ! type ! type ! pos. ! ! ! type *-----------------------------------------------------------------------* * Segment nameFIELD=SEGMENT Y, C, C, 0, 8, 0, ,** Key Feedback AreaFIELD=K_VEAMOID, Y, C, C, 8, 21, 0, , ** Data fields - key (repeated)FIELD=VEAMOID, Y, C, C, 29, 21, 0, , ** Data fieldsFIELD=VEADESC, Y, C, C, 50, 15, 0, , FIELD=VEATIAR, Y, C, C, 65, 1, 0, , FIELD=VEAUNMI, Y, C, C, 66, 2, 0, , FIELD=VEAALIQ, Y, C, C, 68, 2, 0, , ...

To access the segment in a qualified way it is necessary to specify the start key in the program:

* 01 QSSA-VECNTRL. 02 FILLER PIC X(17) VALUE 'VEMOID (VEAMOID '. 02 FILLER PIC X(02) VALUE '= '. 02 FILLER PIC X(21) VALUE LOW-VALUE. 02 FILLER PIC X(01) VALUE ')'. *

To convert these lines into the definition for the SQL Engine, it is necessary to define the field names to be used for the access.

STARTKEY=PCB=0,SSA=VEMOID (VEAMOID >=FIELDS(K_VEAMOID))

January 2011


The SSA specification is passed to DL/I. Therefore, it is necessary to comply with the syntax for SSAs. A syntax error will be reported by the DL/I error message 'AJ' during the access.

During the following access, "K_VEAMOID" is replaced with the value which is defined in the SELECT statement. It is important, that the length of the definition (here: 21 Bytes) corresponds exactly with the DL/I field description.

If the key fields should to be defined separately for the following SELECT, a FTB must be created which defines each key field individually. The following example redefines K_VEAMOID with three individual fields.

** Key Feedback AreaFIELD=K_VEAMOID, Y, C, C, 8, 21, 0, , FIELD=K_VEASOCI, Y, C, C, 8, 2, 0, , FIELD=K_VEAMODE, Y, C, C, 10, 7, 0, , FIELD=K_VEAFILL, Y, C, C, 17, 12, 0, , *

If individual key fields are used to access the segment, these key fields must be defined for the SQL Engine.

STARTKEY=PCB=0,SSA=VEMOID (VEAMOID >=FIELDS(K_VEASOCI,K_VEAMODE,K_VEAFILL))

During a later access "K_VEASOCI,K_VEAMODE,K_VEAFILL" are replaced by the values which are defined in the SELECT statement. It is important, that the length of the definition (2+7+12=21 Bytes) matches exactly the length of the DL/I field description. For a direct access all key words must be defined in the SELECT statement.

Access to a segment on a lower level:

Now, the VEAREA segment must be accessed. To access the segment unqualified, only the specification of the segment name is needed in the program.

* 01 UNQUAL-VEAREA-SSA PIC X(9) VALUE 'VEAREA '. *

That's how the specification would look like for the SQL Engine:

STARTKEY=PCB=0,SSA=VEAREA .

The specification of the SSA is passed to the DL/I. Therefore, it is necessary to comply with the syntax for SSAs. In case of an unqualified access, the segment name must be a 10 character value. If it is actually shorter, the remaining positions will be filled with blanks. It will be followed by a dot. A syntax error will be reported as the 'AJ' DL/I error message 'during the access.

In order to access a segment in a qualified way, the individual fields and the key are defined in Cobol. The following VEAREA sample segment explains these definitions.

* 01 VEAREA PIC X(130) VALUE SPACES. * key.......... 02 VEBAREA PIC X(03). * Data fields ...

January 2011


02 VEBSOCI PIC X(02). 02 VEBDESC PIC X(15). 02 VEBDTST PIC X(06). ... *

The key of this segment cannot appear in several ways. During the import of the copybook, you must consider that each record supplied by the SQL Engine, is prefixed by the segment name - PIC X(08) - and the key feedback area. So the actual data area starts at position 32 ( 8+21+3=32 bytes (8 bytes segment name, 21 bytes key of parent segments, 3 bytes key of VEAREA segment)). Define these fields during the import. Now, the final FTB will look like the following:

** SQL Engine definition file (FTB format)*HOSTFILE=SVEPDBS(DL/I) <- PSB definitonSTARTKEY=PCB=1,SSA=VEMOID (VEAMOID >=FIELDS(K_VEAMOID)), <- see below SSA=VEAREA (VEBAREA >=FIELDS(K_VEBAREA))** ! field ! used ! host ! pc ! start ! length ! scale ! user * ! name ! ! type ! type ! pos. ! ! ! type *-----------------------------------------------------------------------* * Segment nameFIELD=SEGMENT Y, C, C, 0, 8, 0, ,** Key Feedback Area (Parent Segment)FIELD=K_VEAMOID, Y, C, C, 8, 21, 0, , ** Key Feedback Area (Segment)FIELD=K_VEBAREA, Y, C, C, 29, 3, 0, , ** Data fields - Key (repeated)FIELD=VEBAREA, Y, C, C, 32, 3, 0, , FIELD=VEBSOCI, Y, C, C, 35, 2, 0, , FIELD=VEBDESC, Y, C, C, 37, 15, 0, , FIELD=VEBDTST, Y, C, C, 52, 6, 0, , ...

To access the segment qualified it is necessary to define the start key in the program:

* 01 SSA-Q-VEAREA. 02 QSSA-VEAREA. 05 FILLER PIC X(17) VALUE 'VEAREA (VEBAREA'. 05 VEAREA-RO PIC XX VALUE '= '. 05 VEAREA-KEY. 08 VEBAREA-KEY PIC X(03) VALUE SPACES. 05 FILLER PIC X VALUE ')'. *

To convert these lines into the format used by the SQL Engine, it is necessary to define the field names which are to be used for the access.

SSA=VEAREA (VEBAREA >=FIELDS(K_VEBAREA))

January 2011


The following segment is not the root segment. Hence, the additional definition of the root segment is required here. The complete definition looks as follows:

*STARTKEY=PCB=1,SSA=VEMOID (VEAMOID >=FIELDS(K_VEAMOID)), SSA=VEAREA (VEBAREA >=FIELDS(K_VEBAREA))*

or

*STARTKEY=PCB=1,SSA=VEMOID (VEAMOID >=FIELDS(K_VEASOCI,K_VEAMODE,K_VEAFILL)), SSA=VEAREA (VEBAREA >=FIELDS(K_VEBAREA))*

The definition that the definition of the SAA is passed to DL/I. It must comply with the syntax for a SSA. A syntax error will be reported by to the 'AJ' DL/I error message during the access.

Note for access via SQL:

When directly accessing a segment, all key values must be defined within an SQL statement. Otherwise the read will be done sequentially. It is not necessary to use all of the defined key values. If only a partial key is defined, the access positions in the database and then continues sequentially. The key values always must be defined from the left most key field (e.g. "K_VEASOCI and K_VEAMODE"); if only "K_VEAMODE"is defined, tcACCESS can never position on the desired segment, because the left most part of the key is missing.

A note on reading indexed data:

In our previous examples, we always used a SSA definition with ">=" to build up key fields (Example: "SSA=VEAREA (VEBAREA >=FIELDS(K_VEBAREA))"). This is based upon the fact, that the SQL Engine expects data with an index. The access is performed by positioning on a key value and reading forward. This method eliminates the need to define all key values for an access.

In cases, where1. always all key values are defined and2. a single record is always expected as the result

it is possible to replace the accesses with a "="- operator. Defining "SSA=VEAREA (VEBAREA =FIELDS(K_VEBAREA))" has the effect that a direct read is performed and a single record will be returned even for "SELECT ... WHERE KEYVALUE>10". If you want to exercise both access methods, define an individual FTB for every case.

A note for linking subordinated segments using a DL/I PATH call:

If segments in a hierarchy should be processed, this can be accomplished without the need to JOIN these segments using the SQL Engine or in the application program (e.g. MS Query). One simply can concatenate all fields of the "parent" segment and the subordinate segment(s) by creating a FTB file with the following structure:

SEGMENTNAMEPIC X(8)

KEY FEEDBACK AREA- PARENT KEY -

KEY FEEDBACK AREA- CHILD KEY -

DATA AREA- PARENT -

DATA AREA- CHILD -

For the SSA definition it is only necessary to define the command code 'D' (see "IBM DL/I Resource Definition and Utilities" for "PATH CALL").

January 2011


*STARTKEY=PCB=0,SSA=VEMOID *D(VEAMOID >=FIELDS(K_VEASOCI,K_VEAMODE,K_VEAFILL)), SSA=VEAREA *D(VEBAREA >=FIELDS(K_VEBAREA))*

To be able to use the command code *D, the 'P' processing option must be defined within the PCB (see "IBM DL/I Resource Definition and Utilities", chapter "3.1.2.1 PCB Statement", keyword PROCOPT). If this option is not set, the 'AM' status code will result.

Concatenating subordinated segments (key word APPEND): If segments must be chained or concatenated which are in hierarchical order but do not have a key to properly JOIN them, you can use the new key word APPEND= to concatenate up to 8 depending segments to the "Parent"-segment. The records of the depending (child) segment will be concatenated to the record of the main (parent) segment. Between each segment information, the 8-digit name of the segment will be inserted. The additional (up to 8) segments must be specified in a hierarchical descending order. If a "Parent” segment does not have a "Child” segment, the fields of the "Child” segment will be set to NULL, however the record of the "Parent” segment will be returned.

APPEND=segment[,segment…]

Layout of the data record:

SEGMENTNAMEPIC X(8)

SEGMENTNAME (CHILD)PIC X(8)


DATA AREA- PARENT -

DATA AREA- CHILD -

Example: * STARTKEY=PCB=0,SSA=VEMOID (VEAMOID >=FIELDS(K_VEASOCI,K_VEAMODE,K_VEAFILL)) APPEND=VEAREA *

A note for linking segments on the same level (Keyword APPEND_SEQ):

If there is the need to link segments which are on the same level, one can use the keyword APPEND_SEQ to read up to 8 "same-level" segments in addition to the parent segment. All segments that should be read additionally must be on the same hierarchical level.

January 2011


After reading the "Parent“-segments, the "Child“-segment will be read in the specified sequence using the "GNP"-command. The segment data will be appended to the position defined with SEGMENT_DATA=. For better "readability" the 8-digit segment name will be inserted in front of the data. Fields of segments which are currently not being read will contain LOW-VALUES. APPEND_SEQ=segment1SEGMENT_DATA=n1APPEND_SEQ=segment2SEGMENT_DATA=n2[APPEND_SEQ=segment3SEGMENT_DATA=n3]

Layout of the data record:

SEGMENTNAMEPIC X(8)

SEGMENTNAME (CHILD1)PIC X(8)


DATA AREA- PARENT -

DATA AREA- CHILD1 -

n1SEGMENTNAME (CHILD2)PIC X(8)

DATA AREA- CHILD2 -

n2

Example: * STARTKEY=PCB=0,SSA=VEMOID (VEAMOID >=FIELDS(K_VEASOCI,K_VEAMODE,K_VEAFILL)) APPEND_SEQ=VEAREA SEGMENT_DATA=200APPEND_SEQ=VEAREB SEGMENT_DATA=400*

A note on HDAM data bases:

Records in a HDAM data bases are distributed randomly and are not sorted. There are two ways for accessing those segments. To retrieve more than one record, only the unqualified access is possible. Should the access be qualified, the definition of the key fields must be as follows: "segment==FIELDS(keyfields)". Only one record will be returned. This method is recommended, if the complete key of the data record is available.

HDAM_CHECK=[Y|N]

Specification of HDAM_CHECK=N disables the check for '=='. However note, that the usage of '>=' in the SSA causes an uncompleted result set.

A note on SSA search conditions:

The optional parameter REMOVESSASEARCHCONDITIONS=Y allows to modify the internal processing for SSA search conditions. If this parameter is active, the SSA search condition is removed after the initial GU command.

REMOVESSASEARCHCONDITIONS=[Y|N]

January 2011


2.5.1.10 Key words for MVS PS/PDS Files

Definiton of the data source:

HOSTFILE=dsn-name[(member)]

It is necessary to define a data type for MVS files.

Example:

HOSTFILE=QUAL1.QUAL2(MEMB1)

January 2011


2.5.1.11 Keywords for DB2 or SQL/DS The current version of tcACCESS supports 'Joins' between the SQL Engine and DB/2 or SQL/DS. Therefore, the SQL statement to read DB/2 or SQL/DS must be part of a FTB file. Definition of the SQL statement to be executed: SQL_SELECT=SELECT field nameSQL_FROM=FROM tablesSQL_WHERE=WHERE where-clauseSQL_GROUPBY=GROUPBY group-by-clauseSQL_HAVING=HAVING having-clause

SQL_SELECT= defines the part of the SELECT statement defining the column names.. The 'FROM' clause is defined with the 'SQL_FROM' key word. The 'SQL_WHERE=' key word may refer to an option WHERE clause. 'SQL_GROUPBY=' and 'SQL_HAVING=' are provided for grouping functions. Example: SQL_SELECT=SELECT * SQL_FROM=FROM CUSTOMERS SQL_WHERE=WHERE CUSTOMERS.NR > 10000

2.5.1.12 Key words for MVS VSAM Files


HOSTFILE=dsn-name

In a MVS =S/390 System environment it is also possible to directly access VSAM files without defining them within in CICS or the tcACCESS Monitor system. For performance reasons, however, it is recommended to use n FCT definition for CICS or VSAM definition within the Monitor system instead of defining the VSAM cluster directly.

Example:

HOSTFILE=QUAL1.QUAL2.KSDS

Special field for VSAM/RRDS-filesIn order to directly access a data records using the relative record number a field with a name of ‘RRDS_RRN’ must be defined. The SQL-Engine automatically uses this field as a unique key. This field must be defined as FULLWORD and it must be the first in the field definitions and must have an offset of 0.

2.5.1.13 Key words for Batch VSAM Files (VSE) Definition of the data source:

HOSTFILE=dsn-name(BVSAM)

January 2011


In a VSE system environment VSAM files can be accessed directly without having to define them to CICS. To do this, it is necessary that an entry for the file exists in the system standard labels. For performance reasons it is however recommended to access the file by using a CICS-FCT definition of the direct access to a VSAM cluster.

Example:

HOSTFILE=VSAM.ARTICLE.KSDS.FILE(BVSAM)

January 2011


Special key words: HOSTPARM=UC=catalogue

If the VSAM file is not defined in the System Standard Labels, you can use the UC= parameter to specify the catalog, where the file is defined. If the file is part of the Master catalog, simply specify the parameter without a catalogue name. Example: HOSTFILE=VSAM.ARTIKEL.KSDS.DATEI(BVSAM) HOSTPARM=UC=VSESP.USER.CATALOG

2.5.1.14 Key words for SAM files (VSE) Definition of the data source: HOSTFILE=dsn-name(SAM)

SAM or SD files can be accessed in a VSE environment. Example: HOSTFILE=VSE.SEQ.FILE(SAM)

Special key words: * Entry for SAM filesHOSTPARM=00=volser,01=volser,...,RF=xx,LR=nnn * Entry for VSAM Managed SAM file HOSTPARM=UC=catalog,PW=passwort,RF=xx,LR=nnn

The HOSTPARM= key word can be used to specify additional parameter for the SAM file access. All parameter must be defined in one line.

00=volser,01=volser,02=volser,...,FF=volser This parameter defines the extends of the file. = defined the first extent, 1= defines the second etc. A maximum of 15 extends can be specified. Note, that the extend key words must be specified in hexadecimal, (e.g. 0A for the 11th extend)

UC= For VSAM Managed SAM files the catalogue is defined with parameter UC=. If the file is

defined in the master catalogue this parameter must be set without a value.

PW= Password for a VSAM Managed SAM file. RF= Record format of the access data:

FB fixed, blocked F fixed, non blocked

January 2011


VB variable, blocked V variable, non blocked U undefined

LR= For fixed, blocked (RF=FB) files this parameter defines the record length.

Examples: HOSTFILE=VSE.SEQ.FILE(SAM) HOSTPARM=00=DOSRES,01=SYSWK1,RF=FB,LR=123 HOSTFILE=VSE.VSAM.SAM.FILE(SAM) HOSTPARM=UC=VSE.USER.CATALOG

Special field for VSAM/RRDS-filesIn order to directly access a data records using the relative record number a field with a name of ‘RRDS_RRN’ must be defined. The SQL-Engine automatically uses this field as a unique key. This field must be defined as FULLWORD and it must be the first in the field definitions and must have an offset of 0.

2.5.1.15 Key words for DATACOM/DB

To access DATACOM/DB the tcACCESS generation parameter "DCDFLG” must be be set to 'Y'.


HOSTFILE=file_name(DATACOM)

File_name is the 3 Bytes DATACOM file name (the TABLE-ID).

Special key words:

DBID=nnn

This key word determines the DBID nnn of the DATACOM file, if a 'User Requirement' table is to be used. If this specification is omitted, '0' is assumed.

ELEMENTLIST=(element1 element2)

Specification of the elements list for the DATACOM/DB request area. Each element has a 5 digit name and one digit for the security code. The list must be terminated with five blanks and must be included in brackets.

STARTKEY=index-name,FIELDS(key-field[,key-field...])STARTKEY_UNIQUE=index-name,FIELDS(key-field[,key-field...]) STARTKEY_NONUNIQUE=index-name,FIELDS(key-field[,key-field...])

The FIELDS() parameter determines the name of the FIELD= entry for all fields which build the complete key. It is possible to define several STARTKEY key words for each defined index.

January 2011



Example:

HOSTFILE=MTA(DATACOM)DBID=35STARTKEY=INXD1,FIELDS(KA01,KR28)STARTKEY=INXD2,FIELDS(KR28)ELEMENTLIST=(ELEM1 ELEM2 )*FIELD=KA01, Y, P, N, -1, 13, 0FIELD=KR28, Y, P, N, -1, 3,FIELD=A01, Y, P, N, 17, 13, 0FIELD=R28, Y, P, N, 24, 3,

2.5.1.16 Key words for ADABAS

In order to access ADABAS the tcACCESS generation parameter "ADAFLG” must be set to 'Y'. For the import of PREDICT definitions using the PC front-end program, the parameter SYSFNR= and SYSDBNR must be set.


HOSTFILE=description(ADABAS)

Description is a descriptive name; the input is mandatory.

Special key words:

DBNR=nnn

The DBNR nnn of the file.

FNR=nnn

The FNR nnn of the file.

PREFETCH=nnn

This statement allows to specify the number of records which are to be read ahead by the SQL-Engine during one access operation. If the records are mainly to be processed sequentially, a specification of a value between 50 and 100 may considerably increase the processing speed.

ADAPWD=password

January 2011


Specifying 'ADAPWD', it is possible to access an ADABAS table while security is activated. If there are different passwords for a variety of authorizations, the password with the highest authorization needs to be defined.

ADACIPHER=cipher code

‘ADACIPHER’ specifies the ADABAS cipher code for encrypted ADABAS files.

Example:

HOSTFILE=FILE1(ADABAS)DBNR=31FNR=183PREFETCH=10*FIELD=NAME, Y, P, N, 0, 13, 0, 0, AA

Notes for ADABAS:

When accessing ADABAS tables, you can use the special key words "WHERE_ADABAS”, "ADA_AND” and "ADA_OR” which are directly executed under the control of ADABAS.

Special field ADABAS-ISN Using the definition of field ‘ADABAS_ISN’ it is possible to directly access the data records using ISN. The SQL-Engine automatically uses this field as a unique key. The format of the field must be a FULLWORD.

SQL extensions for ADABAS

Using reserved keywords in views which access ADABAS tables, you can use the ADABAS FIND/S1/S2 commands. The FIND/S1/S2 command will pass certain selection criteria directly to ADABAS, hence data selection is performed by ADABAS and not by the SQL-engine. In combination with ADABAS descriptor definitions, this can result in drastic performance enhancements.

WHERE_ADABAS

The WHERE_ADABAS-clause utilizes the syntax of the SQL-WHERE-clause and supports all selection criteria known to the NATURAL FIND command. WHERE_ADABAS and SQL WHERE can be combined. In this case, first the WHERE_ADABAS selections will be done by ADABAS, the result set is returned to the SQL engine and the SQL WHERE conditions are then applied against this result set.. The selected records are passed to the calling application.

The SQL SELECT clause must not contain any Sub/Super/Hyper- and phonetic descriptors, because they are always NULL ((Sx/Lx-commands can not return descriptor values).

If the SELECT clause uses the COUNT(*) expression and selection is performed using the WHERE_ADABAS clause (no SQL WHERE clause), no records will be read by the SQL-engine, because the number of records can be directly obtained from the ISN-quantity field. This leads to significant performance gains, especially when accessing large tables.

Differences to the SQL WHERE clause:

• brackets are not supported• LIKE only supports 'xxx%' • Only a "simple field” name can be specified on the left hand side of the operator (i.e. TAB.FIELD01)• On the right hand side of the operator you can only specify an expression which can be resolved before the

first data access.

A "simple field" is an ADABAS field, a descriptor, a Sub/Super descriptor or a phonetic descriptor.

January 2011


If a Super descriptor is not in alpha numeric format, it is important to note, that the expression on the right hand side of the operator must have the identical number of bytes like the Super descriptor.

Example:

WHERE_ADABAS S1 = '0009' for a Super descriptor in the format 'U' (unpacked) with a length of 4 bytes.

WHERE_ADABAS S1 = 0009for a Super descriptor in the format 'P' (packed) with a length of 3 bytes..

Super descriptors in mixed format (i.e. packed and alphanumeric) you must use the HEXCHR(str) function and the CONCAT operator to create the expression.

WHERE_ADABAS S1 = 'abcd' CONCAT HEXCHR('00003C')for a Super descriptor with a length of 7 bytes, consisting of an alpha numeric field and a packed field.

Because of the fact, that no brackets can be specified you must consider the rules of boolean algebra.

Example:

SELECT * FROM ADABAS.TABELLE WHERE_ADABAS FIELD_AA = '1' or FIELD_AA = '2' and FIELD_AB = '4'

This SQL statement retrieves all records with FIELD_AA = '1' in addition to all records with FIELD_AA = '2' and FIELD_AB = '4'.

SELECT * FROM ADABAS.TABELLE WHERE_ADABAS FIELD_AA IN ('1', '2') and FIELD_AB = '4'

This SQL statement returns all records with FIELD_AA = '1' or = '2' and FIELD_AB = '4'.

Special keywords: ADA_AND and ADA_OR

The standard 'AND'- and 'OR'-connectors, as shown in the above examples, internally result in the ADABAS Connectors 'D' (for AND) and 'O' (for OR). Using the special keywords ADA_AND or ADA_OR will internally use the ADABAS connectors 'Y' and 'R'. For a more detailed description of these connectors refer to the 'ADABAS Command Reference' Section 'Search Buffer'. The 'Y'-connector is supported as of ADABAS version 7.

January 2011


2.5.1.17 Key words for EDN For accessing EDN files, the tcACCESS generation parameter "EDNFLG " must must be set to 'Y'. Data source definition: HOSTFILE=file name(EDN)

File name This parameter specifies the EDN file name of the data source. It can either be a master file

or a chain file. The list of fields must not contain the EDN work area.

If a chain file is specified, the data record is prefixed with the master file key area. One or more fields need to be defined in the field list covering that area. If the master key definition in a chain files field list is divided into several fields, the following key word must be specified in 'data source specific parameter': HOSTPARM=M2=n1,M3=n2,M4=....

Description:

M2=n1 n1 specifies the relative position of the 2nd field of the master key definitionM3=n2 n2 specifies the relative position of the 3rd field of the master key definition

It's possible to enter a maximum of 10 fields (max. entry: M9=). Example HOSTFILE=STLST001(EDN) HOSTPARM=M2=4,M3=6 * FIELD=MKEY1, Y, C, C, 0, 4, 0, FIELD=MKEY2, Y, C, C, 4, 2, 0, FIELD=MKEY3, Y, C, C, 6, 8, 0, FIELD=CHAINFLD1, Y, C, C, 14, 8, 0, FIELD=...

2.5.1.18 Keywords for CA - IDMS ® records For accessing IDMS the tcACCESS generation parameter "IDMSFLG"must be set to 'Y'. Make sure, that the corresponding IDMS access module can be linked during the link edit step. Definition of the data source: HOSTFILE=subschema.area.record(=IDMS)

If the field-list contains a field with a name of “IDMS_DBKEY” and of type FULLWORD, this field will automatically contain the DBKEY of the currently read main record during the access. In addition a unique index will be automatically created for this field. You can use this field in WHERE-clauses to perform a direct access to the main record. The field MUST not be changed during an UPDATE function.

January 2011


This field must be defined in front of the first data-fields of the record. All record fields will be adjourned by 4 bytes. All fields generated from owner records will be inserted in front of this field.

If a value is assigned to this field during an INSERT, a check is performed whether owners should be connected to the record (refer to OWNER_CONNECT=). If this is the case, currency will be established for all owners with connect_type=MANUAL or connect_type=FORCE and the record, and only one CONNECT command is executed. Additional record data will be ignored.

If no owners that must be connected are specified, field IDMS_DBKEY will be ignored during an INSERT function.

Special key words: STARTKEY=[area of set.]set,FIELDS(key-field[,key-field]) STARTKEY_UNIQUE=[area of set.]set,FIELDS(key-field[,key-field]) STARTKEY_NONUNIQUE=[area of set.]set,FIELDS(key-field[,key-field]) STARTKEY=<CALC>,FIELDS(key-field[,key-field]) STARTKEY_UNIQUE=<CALC>,FIELDS(key-field[,key-field])

STARTKEY= statements define possible paths for direct access to certain records. Without a STARTKEY statement only sequential processing is possible.

One or more STARTKEY statements can be included to describe the sorted index sets for the CA-IDMS® record. Those sets were defined to CA-IDMS® using 'OWNER IS SYSTEM'. Only sets sorted in ascending order can be used. If no STARTKEY statement is included, only sequential access to the record is possible. The FIELDS() parameter determines the name of the FIELD= entry for all fields which build the complete key. The area of the index set can only be declared, if it differs from the area of the record. If the CALC key of the record is used for accessing the data, the keyword <CALC> must be specified as key name. Accessing a record with it's CALC key always returns one record only., hence CALC-keys should be defined as the last STARTKEY statements.

If tcACCESS is supposed to maintain the relationship between the main record and owner records during an UPDATE-, INSERT- and DELETE-function, the owners must be defined using the OWNER= parameter. For any of these owner records one or more STARTKEY= statements can be used. A special meaning have owner-calc-keys during a record UDATE. If all fields of the owner-calc-keys are assigned to LOW-VALUES during an UPDATE, the record will be disconnected from the owner. Depending on the fields used in the WHERE clause of the SQL statement, the SQL-Engine chooses the key that should be used to access the record. If none of the key fields are used in the WHERE clause the first STARTKEY definition will be used.

The usage of STARTKEY_UNIQUE= or STARTKEY_NONUNIQUE= instead of STARTKEY= defines this additional index, the SQL-engine can use them to determine the indexes of a table using SYSTEM.SYSIDX. For accessing the data, the difference between (NON)UNIQUE is irrelevant. OWNER=[area of set.]ownerrecord.set,FIELDS([<DBKEY>,]pos(len)[,pos(len)])

If necessary, this key word is used, to resolve set relationships between records, only known to CA-IDMS® to get a relational result set of the record. Each declared owner record will be read using the specified set. The specified fields will be extracted out of the owner record and are inserted into the member record. The fields will be inserted before the member record fields.

January 2011


The FIELDS() parameter determines the position and the length of all fields in the owner record that should be extracted from the owner record.

If the keyword "<DBKEY>" has been used instead of position and length, the DBKEY of the retrieved owner record will be stored as a fullword in the result record. For every information that has been extracted a corresponding field must be defined in the result record. This field can be defined as access index for this owner:

STARTKEY=index-name,FIELDS(owner-dbkey-field)

Index-name can be any name for this additional index field. The name will be used in the treeview-display of the SQL-Engine.

Contrary to the DBKEY-field of the main record this key is not unique. The name of the indexes and the fields can be defined at your choice.

This field has a special meaning during UPDATE and INSERT of records whose owner relationships must be maintained (refer to OWNER_CONNECT=). If a value of –1 is assigned to this field during an INSERT for an owner with connect_type=MANUAL , the positioning and the connect for this owner will not be performed. If a value of 0 has been assigned to this field during an UPDATE, the record will be disconnected from the owner. The area of the owner can only be declared, if it differs from the area of the record. For each owner relationship to be resolved, one OWNER keyword must be defined. If no additional FIND_MEMBER= keyword has been defined, the relations will be processed in the specified sequence.

FIND_MEMBER=ownerrecord.memberrecord,FIELDS([field1][,fieldn])

This definition describes the hierarchical relationship of the specified owners to each other and to the main record.

The FIELDS()-parameter defines the field or fields that should be used as a key-field to position from an owner to his member. If no key has been defined for the Owner-Member-Set, "FIELDS()" must be defined.

If tcACCESS is expected to maintain the Owner-Member relationships during an INSERT, UPDATE and DELETE, for every OWNER= parameter a FIND_MEMBER= parameter must be present.

OWNER_CONNECT=ownerrecord,type

This parameter defines whether and how a CONNECT must be established to the specified Owner record during an INSERT to the main record.

If type has been defined as "AUTOMATIC" prior to the save of the main record only the corresponding owner record will be activated. If the owner record cannot be found, the INSERT will be rejected. A CONNECT command will not be executed.

If type has been defined as "MANUAL" tcACCESS will attempt to activate the corresponding owner record.. The INSERT will not be rejected if the owner record cannot be found. The CONNECT command will be executed when the main record has been saved.

If type has been defined as "FORCE" the same processing like with "MANUAL" takes place. However, the INSERT will be rejected if the owner record has not been found.

To ensure that the owner records can be located for INSERT and UPDATE processes, STARTKEY= parameter should be supplied to locate the owner records. If this connection is missing, the main record will be connected to the first record of the owner records.

January 2011


FOLLOW=[area of set.]record.set,pos FOLLOW=[area of set.]record.set,FIELDS(follow-field)

For every data record of the main table that has been read the specified set will be read and the records in this set will be appended to the records of the main data record at the position specified with pos or at the position specified by follow-field. Every record in the specified set creates a data record which consists of the data of the owner data record and the data of the member. The length of the member data record increases. Fields from those FOLLOW records must not be changed during an UPDATE. These fields will be ignored during an INSERT. The area of the set can only be specified if it differs from the area of the main record. Using additional FOLLOW key words, sets based on the active FOLLOW record can be appended.

READONLY=[YES|NO]

This parameter specifies what mode should be used for the area of this table during @READY. If the parameter is missing or NO has been specified, the @READY will be issued with UPDATE=YES.

WAITRU=n

If there are no more "external request units" available when accessing CA-IDMS this parameter specifies how often it should be tried to establish a connection to CA-IDMS. This is done on a second basis. If the time has expired without a successful connection to CA-IDMS, the request will be cancelled.

PREFETCH=nnn

This parameter specifies the number of records that shoud be read by the tcACCESS SQL-Engine during one access. For mostly sequential processes a specification of 50 to 100 for this parmeter greatly enhances the procssing speed. Examples: The following figure is the data structure diagram for the CA-IDMS® example EMPLOYEE Database:

January 2011


January 2011


Example definition for the EMPLOYEE record: HOSTFILE=SUBSCHEMA.EMP-DEMO-REGION.EMPLOYEE(=IDMS) * STARTKEY=EMP-NAME-NDX,FIELDS(EMP_LAST_NAME,EMP_FIRST_NAME) OWNER=DEPARTMENT.DEPT-EMPLOYEE,FIELDS(0(4))FOLLOW=COVERAGE.EMP-COVERAGE,100FOLLOW=HOSPITAL-CLAIM.COVERAGE-CLAIMS,200* FIELD=DEPT_EMPLOYEE_ID, Y, Z, N, 0, 4, 0 * FIELD=EMP_LAST_NAME, Y, C C, -1, 20, FIELD=EMP_FIRST_NAME, Y, C C, -1, 20, ...FIELD=COV_FIELD1, Y, C C, 100, 20, FIELD=COV_FIELD2, Y, C C, -1, 20, ...FIELD=HOS_FIELD1, Y, C C, 200, 20, FIELD=HOS_FIELD2, Y, C C, -1, 20, ...

Please note: In order to use the resolved owner key field, a sorted index set should be generated for the record DEPARTMENT.

Special returncodes of the IDMS interface:

20E2nnnn Unexpected IDMS Errstat received, Errstat=nnnn.20E29901 Reserved word <dbkey> used as index name20E29902 Find_member definition not complete20E29903 Follow record definition overlaps20E29904 Error in owner definition: owner-definition20E29905 Error in owner_connect definition: owner-connect-definition20E29906 Follow record data position after last field of FTB20E29907 Error in follow definition: follow-definition20E29908 IDMS_DBKEY is not first field in main record field definion20E29909 Error in fields() definition: fields()-definition20E2990A Index name not found. Internal error20E2990B Connect processing: automatic or forced owner not found20E2990C Error in find_member definition: find-member-definition20E2990D No record found for delete. Internal error20E2990E No record found for update. Internal error20E2990F No update on follow set fields20E29910 Connect processing: duplicate record on owner relation change20E29911 Connect processing update on non-path owner field not allowed20E29912 Update on main dbkey value not allowed20E29913 Connect processing: record to connect not found20E29999 Error in tcACCESS generation (IDMSFLG=N or linkedit error)

2.5.1.19 Key words for tcACCESS Virtual Disk


HOSTFILE=VSAM-FCT-name.diskname:pcpath

Description:

VSAM-FCT-name

January 2011


This is a CICS FCT or a tcACCESS Monitor system file definition name of the VSAM cluster created for the virtual disks.

diskname This specification defines the name of a tcACCESS virtual disk which has been formatted in the VSAM cluster.

pcpath This parameter is defines the name of the file where the data is stored on the tcACCESS virtual disk. '/' is used as separation character for directories.

It is not necessary to define a source type.

Example:

HOSTFILE=TCAVDSK.SYSDSK:/TABLES/SYSTEM/SYSTAB.FTB

January 2011


Special key words:

VDISK_FIXLEN=n

If data is saved with a fixed length in a file on the tcACCESS virtual disk, the record length must be defined here. If the specification is omitted, the record length of the file is determined by the occurrence of ASCII CR/LF.

VDISK_BIN=YES

This statement is needed, if data is stored in EBCDIC format in a file. If this specification is missing, it is assumed that data is stored in ASCII format.

Examples:

HOSTFILE=QXBVDSK.DISK1:DATA/HOST.DAT

or

HOSTFILE=QXBVDSK.DISK1:$$$$$$$U/USER.DAT

or

HOSTFILE=QXBVDSK.DISK1:DATA/HOST.DATVDISK_FIXLEN=237VDISK_BIN=YES

January 2011


2.5.1.20 Keywords for the Screen Content Server

The current version of tcACCESS allows the extraction of data from 3270-applications by the SQL-Engine. A 3270 application simply becomes another data-source.

To use this data-source VTAM-LU2 connections will be established to the online-system which hosts the 3270-application. tcACCESS simulates a virtual terminal. Multiple connections to the same target system can be open at the same time. Connection of the same type will be managed in a terminal pool.

How to define this terminal pool and other related installation steps refer to manual 'tcACCESS Customization"', chapter 'Definition of LU2-connections'

Definition of the data-source:

HOSTFILE=Terminal-Pool(LU2)

Description:

Terminal-Pool The name of a terminal pool which has been created for this function.

Example:

HOSTFILE=CICSA(LU2)

In order to access 3270 applications, the SQL-Engine must have information on how to start the application, how to navigate through the application, how to search for certain records, how to extract the data out of the 3270 screens and how to update, delete and insert data.

This will be accomplished by using scripts. These scripts contain information and instructions for the SQL-Engine so that it can simulate a user against the application. These scripts can be developed interactively using a PC-component. The PC-component will also create the definitions for the SQL-Engine (*.FTB file).

Special keywords:

PROJECT=directory-name

This parameter specifies the directoy name of the project in the 'SCRIPTS'-directory on the Virtual Disk.

TRACE=[ Y | N ]

If this parameter is set to'Y' trace-information will be written into TS-queues.

TIMEOUT=n

January 2011


This parameter specifies the time in seconds before a timeout occurs and a script will be cancelled. If this parameter is omitted, 30 seconds are the default.

STARTKEY=start-script,read-script,end-script,FIELDS(field[,field1...])STARTKEY_UNIQUE=start-script,read-script,end-script,FIELDS(...]) STARTKEY_NONUNIQUE=start-script,read-script,end-script,FIELDS(...])

To read screen data a start-read-end script-sequence is needed. The start script will be executed only once to start the application and to eventually position on the key values specified. The read script actually extracts the data from the application and positions to the next data record. The read script will be executed in a loop until an error or the EOF (end-of-file) indicator has been set. The end script will be executed only once to terminate the application.

The FIELDS() parameter specifies the name of the FIELD= entries for all fields, which build the full key.If no group field exists, which combines all key fields, all fields which construct the key must be defined. Multiple STARTKEY keywords may be defined for different indexes.

Using STARTKEY_UNIQUE= or STARTKEY_NONUNIQUE= instead of STARTKEY= state this additional index more precisely for the SQL-Engine function ‚Determination of table indexes using SYSTEM.SYSIDX'. The difference between (NON)UNIQUE has no relevance for the data access.

INSERT_SCRIPT=insert-script

This script contains all necessary steps to call the application and to insert a dat-record based upon the supplied values. If the application does not support the confirmation or cancellation of the insertions, the application should be terminated after the insertion.

READ_UPDATE_SCRIPT=direct-read-scriptWRITE_UPDATE_SCRIPT=update-script

The update of a data-record is a 2 step process. First, the direct-read script positions on the record to be changed and extracts the available field values. Second, the update script will be executed using the changed values. The direct-read-script starts the application, the update-script terminates the application, if no mechanisms is supported by the application to confirm or cancel the changes.

DELETE_SCRIPT=delete-script

This script contains the necessary steps to call the application, search for the data-record and delete it. If the application does not support the confirmation or cancellation of the insertions, the application should be terminated after the deletion.

SYNCPOINT_SCRIPT=commit-script

January 2011


If the application supports a mechanism to confirm or cancel the changes, this script can be used to commit the changes and perform the appropriate steps.

ROLLBACK_SCRIPT=rollback-script

If the application supports a mechanism to confirm or cancel the changes, this script can be used to rollback the changes and perform the appropriate steps.

2.5.1.21 Keywords for the High Performance OST Server (Open System Transparency)

The current version of tcACCESS supports access to and joins with ODBC-data-sources and SQL-engine resources. To do this, the SQL-statement and the corresponding server must be specified in a FTB file. Definition of the SQL-statement:

OSTSERVER=name IPADDRESS=address:port TYPE=[ ODBC | UDB | OCI ] CONNECT=connection string TIMEOUT=maximum wait time in seconds SQL_SELECT=SELECT field names SQL_FROM=FROM table(s) SQL_WHERE=WHERE where-clause SQL_GROUPBY=GROUPBY group-by-clause SQL_HAVING=HAVING having-clause

The parameter to etstablish a connection correspond to the ones in the macro (refer to manual ″tcACCESS Installation & Administration – Customization Parameter″). If the parameter are specified in this definition and in the macro, the parameter defined in the definition overwrite the ones specified in the macro.

SQL_SELECT= is used to specify the SELECT-part of the SQL statement. The ‘FROM’ clause is specified using keyword ‘SQL_FROM’. A ‘WHERE’ can be specified by using keyword ‘SQL_WHERE’ . Grouping functions can be defined using ‘SQL_GROUPBY’ and ‘SQL_HAVING’.

The characters specified with the SQL_...-keywords are passed without any checks to the OST-Server. They must be conform with the required syntax of the target RDBMS.

2.5.1.22 Keywords for the tcACCESS ODBC-access

The current version supports the join between ODBC-data-source and data-sources managed by the SQL-Engine. To accomplish this, the SQL statement must be part of an FTB-file. Definition of the SQL-statement to be executed: TASK_NAME=task-nameCONNECT=odbc connect stringTIMEOUT=timeoutSQL_SELECT=SELECT field namesSQL_FROM=FROM table(s)SQL_WHERE=WHERE where-clauseSQL_GROUPBY=GROUPBY group-by-clauseSQL_HAVING=HAVING having-clause

January 2011


TASK_NAME= specifies the name of a tcACCESS Listener-task, which will perform the access to the ODBC-data-source on the Windows machine.

The PC-Server, which has started the Listener task, must use the executable module 'TCAODCQ.EXE'. This module uses an individual host-connection for every parallel access from the configuration-pool with the same name as defined in parameter TASK_NAME=. The requirement for the server-PC is, that there must be at least as many tcACCESS connection-slots defined using this configuration as there are parallel accesses being expected.

CONNECT= defines the ODBC-connect-string, which will be used to connect to the data-source.

TIMEOUT=- defines the maximum time in seconds the SQL-Engine should wait for the PC-server to answer.

SQL_SELECT= defines the SELECT part of the SQL-statement. 'SQL_FROM' defines the FROM-part of the SQL-statement. A 'WHERE' clause can be defined using 'SQL_WHERE' and grouping functions can be defined with 'SQL_GROUPBY' and 'SQL_HAVING'.

The SQL-statement defined with the SQL_...-keywords will be passed to the ODBC-driver without any modification. Make sure, that the correct syntax has been applied. Example: TASK_NAME=TCA_ODBCCONNECT=DSN=MY_DATABASE;UID=MYUSER;PWD=PASSWORD;TIMEOUT=30SQL_SELECT=SELECT *SQL_FROM=FROM CUSTOMERS SQL_WHERE=WHERE CUSTOMERS.NR > 10000

2.5.1.23 Keywords to access ORACLE (Open System Transparency)

2.5.1.23.1 General

Component „tcACCESS Open System Transparency for Oracle“ allows a direct access to ORACLE databases on either WINDOWS- or UNIX-server. The data flow can happen in different ways:

• Definition of ORACLE-databases as datasources of the SQL-Engine• Access to ORACLE databases using the host utility "TCAISRV"• Access to ORACLE databases from a host batch-job using the utility program "TCASRVUP"

Contrary to the „tcACCESS Open System Transparency for ODBC“ the access to ORACLE databases is not performed using ODBC but the "OCI-interface" („Oracle Call Interface“) is used. OCI is a proprietary low-level API provided by ORACLE.

Usage, implementation and functionality of the "tcACCESS Open System Transparency for Oracle“ is slightly different from the "tcACCESS Open System Transparency for ODBC". Differences and specialities are described in this chapter.

2.5.1.23.2 Supported database versionsSupport is available for the access to Oracle database Version Oracle9(i) using the OCI-modules of that particular version.

2.5.1.23.3 Installation

2.5.1.23.3.1 OCI-Library

January 2011


tcACCESS uses functions provided by the OCI-function-library. The necessary modules are available after the installation of an "Oracle-Client" or "Oracle Instant Clients" (as of Version Oracle10g).

2.5.1.23.3.2 Unix-Operating systemsDuring the installation of the Oracle-client library "libclntsh.so" will be created. This library contains the OCI. tcACCESS must be able to locate the library. Take the name of the directory containing file "libclntsh.so" (i.e. "$ORACLE_HOME/lib"), and add it to "LD_LIBRARY_PATH" (or "SHLIB_PATH" for HP-UX or "LIBPATH" for AIX).

2.5.1.23.3.3 Windows-Operating systemsDuring the installation of the Oracle-client library "oci.dll" will be created. This library contains the OCI. tcACCESS must be able to locate the library. Take the name of the directory containing file "oci.dll" (i.e. "c:\Oracle\Ora91\Bin"), and add it to environment variable "PATH".

Net-Service-NameTo access an Oracle-database using a logical database-name, a so-called "Net-Service-Name" must be configured on the local machine. During the database access the "Net-Service-Name" will be resolved into the required information like network address or the database service-name. You can use the "Net Manager"-program from Oracle to configure the "Net-Service-Name" (i.e. call program "netca" in directory "ORACLE_HOME/bin" for a UNIX system). Additional information about the configuration of the "Net- Service-Name" can be found in the Oracle documentation.

Note: The Net-Service-Name always must be defined for "tcACCESS Open System Transparency for Oracle" when parameter "DSN=" is required for the connection-string.Alternatively a connection-string with the following syntax can be used::

(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=dbhost) (PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=db1)))

Starting with Version Oracle10g a connection-string with the following syntax can be used:

//host:[port][/service name]

Using the last two methods does not require the configuration of a local „Net Service Name“ .

2.5.1.23.4 Access types

Oracle-database is a data-source of the SQL-EngineOracle-databases can be defined as tables to the SQL-Engine like a VSAM file or an IMS-segment. This allows a direct access to the Oracle-data by the SQL-Engine and permits a JOIN with other data-sources defined to the SQL-Engine.

To define an Oracle-data-source as an SQL-Engine table, an "SQL-statement" and additional parameter for the access to the Oracle-table (or to a View) will be defined in the FTB.

TASK_NAME=task nameCONNECT=connect stringTIMEOUT=timeoutSQL_SELECT=SELECT field-namesSQL_FROM=FROM table(s)SQL_WHERE=WHERE where-clauseSQL_GROUPBY=GROUPBY group-by-clause

January 2011


Example:

TASK_NAME=ORADATACONNECT=DSN=ORADB1;UID=SCOTT;PWD=TIGERTIMEOUT=30SQL_SELECT=SELECT *SQL_FROM=FROM SCOTT.ARTICLE

"TASK_NAME" defines the name of the task to be started by the tcACCESS-Listener. This task will be responsible for the access to the Oracle-database. Define "tcasoraq.exe" in the tcACCESS installation directory as the "Program to be started" in the task definition.

Parameter "DSN=” in the "connect string" specifies the "Net-Service-Name" of the Oracle-database. The name must be defined as described in the "Installation"-section. Parameter "UID=" and "PWD=" specify the "Oracle-User name" and the password. The specification of "UID=" and "PWD=" is mandatory.

Access to an Oracle-database using the Host-API "TCAISRV"Access to Oracle-databases from a host-program is identical to the description of "tcACCESS Open System Transparency for ODBC". AN example can be found in the "tcACCESS V6.0 Procedure Manual" chapter " Query and change ODBC-data on a PC from the host". Notice however, that parameter "DSN=" must have the following format:

DSN=Net-Service-Name;UID=Oracle-UserId;PWD=Password

"Oracle-UserId" and "Password" ALWAYS MUST BE SPECIFIED.

The task specified with the "TN"-parameter must have program "tcasoraq.exe" defined as "Program to be started". The program can be located in the tcACCESS installation directory.

Access to Oracle-databases using the Host Utility-Program ‘TCASRVUP’

Another possibility is to access an Oracle-database by a host batch-program. The tcACCESS utility TCASRVUP can be used.

Example: JCL needed to access an Oracle-database using "Open System Transparency for Oracle"

//TCAORA JOB ,'RUN THE SRV U PGM',CLASS=A,MSGCLASS=A//*//STEP1 EXEC PGM=TCASRVUP,REGION=0M//STEPLIB DD DISP=SHR,DSN=TCACCESS.V800.LOADLIB//SYSPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSIN DD **CONNECT PORT3020TRACE OFFMODULE TCASODCQUSER MILLERPWD ABC123NUM2ZONE YESNUMEDIT YESDBL2CHAR YESNULLS YESQUOTEHOSTPARMS CS=DSN=ORADB1;UID=SCOTT;PWD=TIGER;,TN=ORADATAEXECSQL SELECT * FROM SCOTT.ARTICLE;$$$END

January 2011


Parameter "DSN=” defines the "Net-Service-Name" of the Oracle-database. Parameter "UID=" and "PWD=" specify the "Oracle-UserId" and the password. The specification of "UID=" and "PWD=" is mandatory.

For the tcACCESS Listener task definition, the task-name defined with "TN=" must specify "tcasoraq.exe" as the "Program to be started". It can be located in the tcACCESS installation directory.

2.5.1.24 Keywords to access DB2 UDB (Open System Transparency)

2.5.1.24.1 GeneralComponent „tcACCESS Open System Transparency for DB2 UDB“ allows a direct access to DB2 UDB databases on either WINDOWS- or UNIX-server. The data flow can happen in different ways:

• Definition of DB2 UDB-databases as datasources of the SQL-Engine• Access to DB2 UDB databases using the host utility "TCAISRV"• Access to DB2 UDB databases from a host batch-job using the utility program "TCASRVUP"

Contrary to the „tcACCESS Open System Transparency for ODBC“ the access to DB2 UDB databases is not performed using ODBC but DRDA protocol and TCP/IP

The use, implementation and functionality of "tcACCESS Open System Transparency for DB2 UDB" slightly differ to the "tcACCESS Open System Transparency for ODBC". Differences and points of interest will be covered in this document.

2.5.1.24.2 Supported database versionsSupport is currently available for the following DB2 UDB version:

• DB/2 Server for OS/390 and z/OS as of Version 5.1• DB/2 Server for VSE as of Version 7.1• DB/2 Server for VM as of Version 6.1• DB/2 for Windows NT as of Version 7.1• DB/2 for Linux (intel) as of Version 7.1• DB/2 for AIX as of Version 7.1• DB/2 Server on IBM-iSeries (OS/400) as of Version 4.5

2.5.1.24.1 InstallationThe component „tcACCESS Open System Transparency for DB2 UDB“ is part of the standard tcACCESS installation and does not require a special installation.

2.5.1.24.2 Access typesDB2 UDB-databases as datasource of the SQL-EngineDB2 UDB can be defined as SQL-Engine tables similar to other host resource (i.e.VSAM files). The SQL-Engine can directly access DB2 UDB databases and allows allows joins between DB2 UDB and other host resources.

To define a DB2 UDB-datasource as SQL-Engine table it is necessary to define an SQL-statement and other parameter in a FTB definition. This FTB is used to access the DB2 UDB table (or view)..

TASK_NAME=task nameCONNECT=connect stringTIMEOUT=timeoutSQL_SELECT=SELECT field namesSQL_FROM=FROM table(s)SQL_WHERE=WHERE where-clauseSQL_GROUPBY=GROUPBY group-by-clause

Example:

January 2011


TASK_NAME=DEFAULTCONNECT=HOST=AXEL2;PORT=50000;DATABASE=SAMPLE;UID=DB2INST1;PWD=DB2INST1;TIMEOUT=30SQL_SELECT=SELECT *SQL_FROM=FROM DB2INST1.EMPLOYEE

"TASK_NAME" specifies the task for the tcACCESS listener and is responsible for the access to the DB2 UDB database. In the task definition specify program "tcasudbq.exe" as "program to be executed". This program resides in the tcACCESS installation directory.

Parameter "CONNECT=" has the following options:HOST=...........................................hostnamePORT=............................................port DATABASE=.................................database name;UID=...............................................user IDPWD=.............................................passwordTRACE=.........................................[Y|N] trace setting CTB=..............................................[Y|N] cut trailing blanksPLAN=............................................plan name, i.e. NULLIDPACKAGE=...................................package name, i.e. SQLLF000CONSTOK=...................................consistency token, i.e. 6841446351614450EOS=..............................................[Y|N] error messages on screen

2.5.1.24.3 Access to DB2 UDB-databases using the host API "TCAISRV"Access to DB2 UDB-databases from host programs is performed as described in chapter "tcACCESS Open System Transparency for ODBC". You can find a detailed example in manual "tcACCESS V7.0 process and procedures“ chapter "Query and change ODBC-data from a host application". Please not, that parameter "CS=" must be defined in the format

CS=HOST=…

"DB2 UDB-user ID" and "Password" must ALWAYS be defined.

For the tcACCESS Listener task definition, the task-name defined with "TN=" must specify "tcasudbq.exe" as the "Program to be started". It can be located in the tcACCESS installation directory. 2.5.1.24.4 Access to DB2 UDB-databases using the host utility-program ‘TCASRVUP’Another possibility is to access a DB2 UDB-database by a host batch-program. The tcACCESS utility TCASRVUP can be used.

Example: JCL needed to access a DB2 UDB database using "Open System Transparency for DB2 UDB"

//TCAUDB JOB ,'RUN THE SRV U PGM',CLASS=A,MSGCLASS=A//*//STEP1 EXEC PGM=TCASRVUP,REGION=0M//STEPLIB DD DISP=SHR,DSN=TCACCESS.V800.LOADLIB//SYSPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSIN DD **CONNECT PORT3020TRACE OFFMODULE TCASODCQUSER MEIERPWD ABC123NUM2ZONE YESNUMEDIT YESDBL2CHAR YESNULLS YESQUOTEHOSTPARMS CS=HOST=AXEL2;PORT=50000; HOSTPARMS ADD DATABASE=SAMPLE;UID=DB2INST1;

January 2011


HOSTPARMS ADD PWD=DB2INST1;TRACE=Y; HOSTPARMS ADD CTB=Y;PLAN=TCEXPRESS; HOSTPARMS ADD PACKAGE=TCELF000;CONSTOK=6841446351614450; HOSTPARMS ADD EOS=N;DEFSYSTAB=Y;UII=Y;, HOSTPARMS ADD TN=DEFAULT, EXECSQL SELECT * FROM DB2INST1.EMPLOYEE; $$$END

For the tcACCESS Listener task definition, the task-name defined with "TN=" must specify "tcasudbq.exe" as the "Program to be started". It can be located in the tcACCESS installation directory.

January 2011


2.5.2 Views

A 'view' represents a table whose data (rows and columns) is generated during run-time by using a SELECT statement. 'Views' may be used to only make certain fields or data areas 'visible' to a user or to provide a logical view over different data resources (JOINs). The data tables which result from a 'view' again can be processed by the end-user using SELECT statements.

A 'view' basically is a pre-defined SELECT statement; the SELECT statement is stored in a file with the extension VTB on the virtual disk of the SQL Engine. VIEW and FTB names should be different from each other. The SQL-engine always searches for a FTB first. A VTB definition can only be used, if there is no FTB definition with the same name.

January 2011


2.5.3 Exit Program for user specific data fields

Fields with a user specific format (e.g. date fields) can not be handled by the SQL Engine directly. To process these fields, the field exit program must be customized. For read accesses this program converts user specific data in a format which can be processed by the SQL Engine (e.g. for a SELECT statement). For write accesses standard formats are converted into the required user specific formats (e.g. INSERT).

The name of the program must be TCAU1. To activate the exit program the GU1 parameter must be set to 'Y' in the server module generation. During the link edit of the generation the TCAU1 module is linked.

An example is provided under the name TCAU1(.A) on the tcACCESS MACLIB or library.

Call:

The program is called via a COMMAREA address in register 1.

USF DSECTUSFRC DS H RETURN CODEUSFNAME DS CL32 NAME OF THE FIELDUSFTYP DS CL1 HOSTTYPE C,V,..* C'C' CHARACTER CLX* C'L' MEMO W. LENGTH H,CLX * C'M' MEMO W/O LENGTH CLX ** C'V' VAR CHARACTER, H,CLX* C'Z' ZONED CLX* C'P' PACKED PLX* C'B' BINARY CLX* C'H' HALFWORD H* C'F' FULLWORD F* C'D' DATE CL10 YYYY-MM-DD* C'T' TIME CL8 HH.MM.SS* C'S' TIMESTAMP CL26 YYYY-MM-DD-HH.MM.SS.* MMMMMMUSFNULL DS CL1 IF SET TO X'01', FIELD VALUE IS NULLUSFUTYP DS CL1 USERTYPE 128 OR GREATERUSFFUN DS CL1 X'01': CONVERT USER INPUT FORMAT TO STANDARD OUT* X'02': CONVERT STANDARD INPUT TO USER OUTPUT* X'03': SET OUTPUT TO USER LOW VALUEUSFDLEN DS H DEFAULT BINARY LENGTH OF FIELDUSFDPRE DS H DEFAULT PRECISION OF FIELDUSFDSCA DS H DEFAULT SCALE OF FIELDUSFOLEN DS H OUTPUT BINARY LENGTH OF FIELDUSFOPRE DS H OUTPUT PRECISION OF FIELDUSFOSCA DS H OUTPUT SCALE OF FIELDUSFIAD DS F INPUT VALUE ADDRESS, 0 IF NO INPUT VALUEUSFOAD DS F OUTPUT VALUE ADDRESS 0 IF NO OUTPUT VALUEUSFWORK DS F POINTER TO 100 BYTE WORK AREAUSFDCCF DS H DEFAULT CCSID OF FIELDUSFOCCF DS H OUTPUT CCSID OF FIELD

January 2011


Field description:

Field name: Input/ Output

Description

USFRC: Output Return codeA return code of 0 informs the SQL Engine that the data has been converted successfully. An error can be indicated by using a value between 1 and 255. The processing of the SQL statement is then terminated with an error message.

USFNAME: Input The name of the field as it is defined in the FTB file.USFTYP: Input Host type of field as it is defined in the FTB file:

Type Description Assembler Notation 'C' character CLx'L' memo with length H + CLx field'M' Memo without CLx length field'V' Var string H + CLx'Z' packed + sign. CLx'P' packed PLx'B' binary CLx'H' Half word H'F' Full word F'D' Date CL10 'YYYY-MM-DD''T' Time CL8 'HH.MM.SS''S' Time stamp CL26 'YYYY-MM-DD-HH.MM.SS.MMMMMM'

USFNULL: Output If x'01' is set, the output is interpreted as NULL.USFUTYP: Input Value of the subtype as defined in the FTB file (>= 128).USFFUN: Input Determines the function which is to be processed by the field exit program:

X'01' The value addressed by the USFIAD parameter is to be converted from the user specific format into the USFTYP standard format. The converted data will be written into the address section referenced by the USFOAD parameter. The output format is mandatory and may not be changed. The length of data and eventually the number of numerals and fractions must be defined for the SQL Engine in USFOLEN, USFOPRE and USFOSCA (not applicable for half word, date etc.)

X'02' The value addressed through the USFIAD parameter is to be converted from the USFTYP standard format into a user specific format. The converted data will be written into the address section referenced by the USFOAD parameter.

X'03' The address section of the USFOAD parameter is to be reduced to the smallest possible value which may be assumed by the user specific format (e.g. low value).

USFDLEN: Input Physical length of the field as defined in the FTB file.USFDPRE: Input Number of digits of the field as defined in the FTB file.USFDSCA: Input Number of fractions of the field as defined in the FTB file.USFOLEN: Output Physical length of the standard format output after the conversion.USFOPRE: Output Number of digits of the standard format after the conversion.USFOSCA: Output Number of fractions of the standard format after the conversion.USFIAD: Output Address of input value. If this field is '0', no input value is available.USFOAD: Output Address of output value. If this field is '0', no output value is needed. The field exit

program can be called with USFFUN=x'01' and USFOAD=0 in order to ask for the characteristics of the user specific format in the standard format.

USFWORK: Output Address of a 100 Bytes size work area which may be freely used by the exit program.

USFDCCF Input CCSID of field as defined in the FTBUSFOCCF Output CCSID of field after the conversion.

January 2011


January 2011


2.6 Stored Procedures

A 'Stored Procedure' consists of a CICS program or tcACCESS Monitor program which accesses a data source. Complex interdependences between several data sources can be processed by using a (already existing) program. If you can use existing business logic, there may be no need to define sequences of SQL commands to access your data resources. The client application just needs to call the procedure with the appropriate parameter. The called program can access all resources which are available within the monitoring system – with the exception of terminal I/Os.

2.6.1 Definition of a Stored Procedure:

Stored procedures are defined like tables or 'views'. They are stored in an ASCII text file on the tcACCESS virtual disk. The files have the extension STP.(see '2.5.1 Table Definition', page 63).

Example:

\TABLES\TEST\TIMEPROC.STP

The procedure shown in the above example is called with the following SQL statement:

CALL TEST.TIMERPROC

Key words for definition:

LOADMODULE=module_name

This key word specifies the program name of a 'Stored Procedure'. In a CICS environment the program name must be defined in the CICS-PPT or definition can be made using RDO. For the tcACCESS Monitor system an entry is required in the PROGRAMS system definition member.

PARMLIST=parameter list

This key word determines the parameter which are passed to the procedure. These parameter are expected in the SQL CALL statement. If the number or format of the CALL statement parameter does not match with the defined parameter list, the call will be rejected with an error message.

The parameter must be defined in the following format:

parameter_name data_type parameter_type,...

January 2011


Description:

parameter_nameName of the parameter. For output parameter this is the column header of the result table.

data_type Description for the data type of the parameter.

Name Type Length Symbolic COBOL NotationINT integer 4 PIC 9(8) COMPSMALL integer 2 PIC 9(4) COMPDEC(p,s) packed p/2 + 1 PIC 9(p-s)V9(s) COMP-3CHAR(n) character n PIC X(n)VARCHAR(n) varchar n+2 PIC 9(4) COMP, PIC X(n) DATE date 10 PIC X(10) ‘yyyy-mm-dd’TIME time 8 PIC X(8) ‘hh.mm.ss’TIMESTAMP timestamp 26 PIC X(26) ‘yyyy-mm-dd-hh.mm.ss.nnnnnn’INT integer 4 PIC 9(8) COMP

parameter_type This option determines the I/O type of the parameter. Possible specifications are IN, OUT or INOUT. IN parameter are used as input for a procedure, OUT parameter will return the results to the client. INOUT parameter may contain input for a procedure and they me be used by the procedure to return the results. All OUT and INOUT parameter together build the result table of the CALL statement. The result table can be processed by a client in the same way as a SELECT result table. Output of a 'Stored Procedure' is considered by the SQL Engine as a result table with one data line.

CCSID nnn This keyword is valid when the Global Language Pack is used. If the keyword is specified, the character fields that are passed to the Stored Procedure are translated before and after the call. If a number has been specified after CCSID, this CCSID is used for translation. If no number has been specified, the CCSID defined in the tcACCESS customization will be used (parameter CP=).

It is possible to define multiple parameter separated from each other with a comma.

Example:

The name of the STP file is \TABLES\TEST\TIMEPROC.STP

* Stored Procedure or the sample date/time procedure*PARMLIST=SWITCH SMALL IN, DATE DATE OUT, TIME TIME OUT*LOADMODULE=TCATIMEQ

The CALL statement is as follows:

CALL TEST.TIMEPROC (3);

The result table looks like the following:

DATE------ TIME----1999-01-11¦16.54.25

January 2011


2.6.2 Stored Procedures COMMAREA

The 'Stored Procedure' is called using the following COMMAREA:

Field name Type COBOL Notation Description

STP_LENGTH FULLWORD PIC 9(8) COMP Length of the COMMAREA including input and output parameter. This value must not be modified by the program.

STP_MODULNAME CHAR(8) PIC X(8) Program name of the procedure.STP_RC FULLWORD PIC 9(8) COMP Return code.

A return code of 0 indicates a successful operation to the SQL Engine. An error can be stated with a value greater than 0.

STP_NR_INPARMS HALFWORD PIC 9(4) COMP Number of the consecutive input parameter. This value must not be modified by the program.

STP_NR_OUTPARMS HALFWORD PIC 9(4) COMP Number of the consecutive output parameter. This value must not be modified by the program.

STP_USERID CHAR(8) PIC X(8) Current user identification; the user is administrated by tcACCESS under this name.

STP_RES1 CHAR(24) PIC X(24) Reserved.STP_PARAM1_NULL HALFWORD PIC 9(4) COMP Parameter 1 NULL indicator

1 = not NULL input parameter-1 = NULL output parameter

STP_PARAM1_VALUE ? ? Parameter 1 value (length and type depending on definition in STP file).

STP_PARAM2_NULL HALFWORD PIC 9(4) COMP Parameter 2 NULL indicator.STP_PARAM2_VALUE ? ? Parameter 2 value (length and type

depending on definition in STP file).... Parameter 3 up to n.

If the program modifies INOUT or OUT parameter, it is necessary to define the appropriate NULL indicators for these fields.

January 2011


2.6.3 Special form of a Stored Procedure

A 'Stored Procedure' without INOUT or OUT parameter is not considered a query by the SQL Engine. This makes it possible for a 'Stored Procedure' to return more than a single data line as result table. This result table is written to a temporary medium (Output of a 'Stored Procedure' is considered by the SQL Engine as a result table with a single line.).

For example, this type of procedure can write its result table to a TS queue, which may then be read by a subsequent SELECT statement. The name of the TS-Queue should be built by using a literal and the field STP_TRMID.

Example:

-- The procedure writes into TS queue MYPRterm (term = STP_TRMID); CALL TEST.MYPROC (1, 'input');--;-- WORKTSQ.FTB uses MYPR$$$T(TS)as host_name;SELECT * FROM TEST.WORKTSQ;

2.6.4 Stored Procedure Example

The following example returns the current date and time of the host. The source code is provided under the name TCATIMEQ(.C) on the tcACCESS MACLIB or library.

IDENTIFICATION DIVISION. PROGRAM-ID. TCATIMEQ. AUTHOR. JOE SAMPLE. * ************************************************************** * DETERMINE CURRENT HOST DATE/TIME * * PARM1 CONTROLS OUTPUT * IF PARM1 = 1 --> RETURN DATE * IF PARM1 = 2 --> RETURN TIME * IF PARM1 = 3 --> RETURN DATE + TIME * ************************************************************** ENVIRONMENT DIVISION. DATA DIVISION. WORKING STORAGE SECTION. 01 WS-TIME. 05 WS-TIME-N PIC 9(8). 05 FILLER REDEFINES WS-TIME-N. 10 FILLER PIC X(2). 10 WS-HH PIC X(2). 10 WS-MM PIC X(2). 10 WS-SS PIC X(2). LINKAGE SECTION. 01 DFHCOMMAREA. 05 STP-LENGTH PIC 9(8) COMP. 05 STP-MODULENAME PIC X(8). 05 STP-RC PIC 9(8) COMP. 05 STP-NR-INPARMS PIC 9(4) COMP. 05 STP-NR-OUTPARMS PIC 9(4) COMP. 05 STP-USERID PIC X(8). 05 STP-TRMID PIC X(4).

January 2011


05 STP-RES1 PIC X(20). 05 STP-PARM1-IN. 10 STP-PARM1-NULL PIC 9(4) COMP. 10 STP-PARM1-VALUE PIC 9(4) COMP. 05 STP-PARM2-OUT. 10 STP-PARM2-NULL PIC 9(4) COMP. 10 STP-PARM2-DATE PIC X(10). 05 STP-PARM3-OUT. 10 STP-PARM3-NULL PIC 9(4) COMP. 10 STP-PARM3-TIME PIC X(8). PROCEDURE DIVISION. * VERIFIES IF SUFFICIENT COMMAREA IS DELIVERED IF LENGTH OF STP NOT = STP-LENGTH MOVE 1 TO STP-RC EXEC CICS RETURN END-EXEC. * RETURN CODE PREDEFINITION, IF PARAMETER 1 INCORRECT MOVE 2 TO STP-RC. EXEC CICS ASKTIME ABSTIME(WS-ABSTIME) END-EXEC. * INVESTIGATION PARAMETER 1 (FILLED AND 1,2 OR 3) IF STP-PARM1-NULL = 1 IF STP-PARM1-VALUE = 1 OR STP-PARM1-VALUE = 3 * RETURN DATE, SET PARAMETER 2 TO NON NULL EXEC CICS FORMATTIME ABSTIME(WS-ABSTIME) YYYYMMDD(WS-DATE) DATESEP('-') NOHANDLE END-EXEC MOVE WS-DATE TO STP-PARM2-DATE MOVE 1 TO STP-PARM2-NULL MOVE ZERO TO STP-RC END IF IF STP-PARM1-VALUE = 2 OR STP-PARM1-VALUE = 3 * RETURN TIME, SET PARAMETER 3 TO NON NULL EXEC CICS FORMATTIME ABSTIME(WS-ABSTIME) TIME(WS-DATE) TIMESEP('.') NOHANDLE END-EXEC MOVE WS-DATE TO STP-PARM3-TIME MOVE 1 TO STP-PARM3-NULL MOVE ZERO TO STP-RC END IF END-IF. EXEC CICS RETURN. GOBACK.

2.6.5 Stored Procedures defined using the GUI

A 'Stored Procedure defined using the GUI' can be defined or imported with the tcACCESS front-end program from an existing CICS-program or tcACCESS VTAM Monitor-program starting from the COMMAREA definition. This means that existing programs can be used without modifications and without an additional

January 2011


interface program. Fields of the COMMAREA can be designated as INPUT-, OUTPUT- or INPUT/OUTPUT-fields. Non-INPUT-fields of the COMMAREA can be initialized with default values.

After the COMMAREA fields have been defined with default values and calling parameter the defined program will be called and the caller of the ‘Stored Procedure‘ receives a result row that contains the fields indicated as OUTPUT and INPUT/OUTPUT.

Using the keywords COMMAND= and result set= fields of the COMMAREA can be changed or additional result sets can be passed to the caller. Using the keywords EXIT_SET_WHEN and EXIT_ALL_WHEN in SQL_SELECT an 'EOF'-condition can be defined. After the condition is TRUE, the corresponding set will be closed and the overall processing of the ‘Stored Procedure‘ will be terminated.If none of the keywords EXIT_SET_WHEN or EXIT_ALL_WHEN have been specified in result set= the defined program will be called once. If a keyword EXIT_SET_WHEN or EXIT_ALL_WHEN has been used, the defined program will be called multiple times and also multiple rows will be returned until an EOF-condition becomes TRUE.

January 2011


2.6.6 Definition of a Stored Procedure with GUIThe definition of a 'Stored Procedure with GUI' is performed in the same way as the definition of a 'Stored Procedure'. Refer to the descriptions in chapter 2.6, the exception is keyword 'PARMLIST=', this is not being used.

Keywords for the definition:

The fields of the COMMAREA as well as the calling parameter are defined using 'FIELD='-definitions . Also refer to chapter Key word FIELD= 2.5.1.2.

COMMAREA_OFFSET=n

This keyword defines an offset in the defined fields where the COMMAREA of the corresponding program begins. This allows the definition of working storage fields in front of the actual COMMAREA. These fields can be used by the 'Stored procedure'. An example could be to save the calling parameter that might be used for conditions in the following result sets.

Example:COMMAREA_OFFSET=32

result set=SQL SELECT

This keyword defines a result set via a SQL-SELECT that will be returned to the caller. A table name of 'COMMAREA' can be used to reference fields in the COMMAREA.

Example:result set=SELECT * from COMMAREA;

COMMAND=SQL UPDATE

This keyword defines a SQL-UPDATE to fields of the COMMAREA.

Example:COMMAND=UPDATE COMMAREA SET STPP1VAL=STPP1VAL+1;

Example of a 'Stored Procedure' with GUI-definition:

*LOADMODULE=TCASTP1COMMAREA_OFFSET=32*COMMAND=UPDATE COMMAREA SET STPP1VAL=STPP1VAL+1;result set=SELECT * from COMMAREA EXIT_ALL_WHEN STPRC > 0;COMMAND=UPDATE COMMAREA SET STPP1VAL=STPP1VAL+1;result set=SELECT * from COMMAREA EXIT_ALL_WHEN STPRC > 0;COMMAND=UPDATE COMMAREA SET STPP1VAL=STPP1VAL+1;result set=SELECT * from COMMAREA EXIT_ALL_WHEN STPRC > 0;**----------------------------------------------------------------------------------* 32 BYTE WORK AREA:FIELD=INONLY, I, H, , -1, 2, 0, 0, , 0, 0, , , , FIELD=INOUT, B, H, , -1, 2, 0, 0, , 0, 0, , , ,FIELD=OUTONLY, O, H, , -1, 2, 0, 0, , 0, 0, , , ,199FIELD=TEMPVAR, Y, F, , -1, 4, 0, 0, , 0, 0, , , ,123FIELD=FILLER, Y, C, , 0, 32, 0, 0, , 0, 0, , , ,* COMMAREA:FIELD=STPLEN, Y, F, , 0, 4, 0, 0, , 0, 0, , , ,78 FIELD=STPMOD, Y, C, , -1, 8, 0, 0, , 0, 0, , , ,'TCASTP1'

January 2011


FIELD=STPRC, Y, F, , -1, 4, 0, 0, , 0, 0, , , ,0FIELD=STPINPAR, Y, H, , -1, 2, 0, 0, , 0, 0, , , ,1FIELD=STPONPAR, Y, H, , -1, 2, 0, 0, , 0, 0, , , ,3FIELD=STPUSER, Y, C, , -1, 8, 0, 0, , 0, 0, , , ,USER()FIELD=STPTRMID, Y, C, , -1, 4, 0, 0, , 0, 0, , , ,CONNECTION_ID()FIELD=STPRES1, Y, C, , -1, 20, 0, 0, , 0, 0, , , ,FIELD=STPP1NUL, Y, H, , -1, 2, 0, 0, , 0, 0, , , ,1FIELD=STPP1VAL, B, H, , -1, 2, 0, 0, , 0, 0, , , , FIELD=STPP2NUL, Y, H, , -1, 2, 0, 0, , 0, 0, , , ,FIELD=STPP2VAL, 0, C, , -1, 10, 0, 0, , 0, 0, , , ,FIELD=STPP3NUL, Y, H, , -1, 2, 0, 0, , 0, 0, , , ,FIELD=STPP3VAL, 0, C, , -1, 8, 0, 0, , 0, 0, , , ,FIELD=FILLER Y, C, , -1, 32, 0, 0, , 0, 0, , , ,

January 2011


2.7 SQL Engine Security

tcACCESS verifies, if a user has the adequate authorization for each of the tables or 'views' referenced in an SQL statement. The character string 'SQL_' + the resource name is checked.

If a 'view' is defined in an SQL statement, the name of the 'view' but not the name of the tables this view uses is verified. If 'Y' is defined for the generation parameter CRESEC of the server module, it will be verified whether the user has read access authorization for the resource 'SQL_' + creator of each object referenced in a 'view'.

Example:

SELECT * FROM CRE1.TABLE1 TB1, VRE2.VIEW1 VW1

Before the SELECT statement is executed, it will be verified if the user has read access authorization to 'SQL_CRE1.TABLE1' and 'SQL_CRE2.VIEW1'.

January 2011


2.8 Technical Information

2.8.1 Catalog Functions

During the installation four files are copied into the SYSTEM subdirectory on the virtual disk. This directory is used by the SQL Engine.

• SYSTAB.FTB• SYSCOL.FTB• SYSIDX.FTB • SYSPROC.FTB• SYSSTAT.FTB• SYSPCOL.FTB

These files are needed by the tcACCESS Manager and the ODBC connection for table and field requests. The SYSTAB and SYSCOL tables return information on the existing tables and 'views' and the columns of these tables or 'views'. The SYSPROC and SYSPCOL tables provide information on the defined 'Stored Procedures' and the parameter used by these procedures.

These tables may be accessed by authorized administrators to get an overview on the available resources:

SELECT * FROM SYSTEM.SYSTAB;

This statement will display an overview of all defined tables and views.

Columns of the table SYSTAB:TNAME CHAR(32) Name of table or viewTYPE CHAR(1) Type: T=table, V=viewTCREATOR CHAR(32) Creator of the table or view

SELECT * FROM SYSTEM.SYSCOL WHERE TNAME = 'tname' AND TCREATOR = 'tcreator';

This statement will display an overview of all defined fields (columns) for the table or 'view' tcreator.tname. The WHERE clause is mandatory. If it is missing, the SELECT statement will not be processed.

Columns of the SYSCOL table:TNAME CHAR(32) Name of table or viewCNAME CHAR(32) Column nameTYPE CHAR(8) Type (CHAR, DATE, TIME, DECIMAL, INTEGER, SMALLINT)LENGTH SMALLINT Column length (number of all digits or characters)PRECISION SMALLINT Number of digitsSCALE SMALLINT Number of fractionsTCREATOR CHAR(32) Creator of the table or view

SELECT * FROM SYSTEM.SYSIDX

WHERE TNAME = 'tname' AND TCREATOR = 'tcreator';

This statement returns a table, which displays information found about all indexes for table or view tcreator.tname. The WHERE clause must be specified. If omitted, the SELECT statement will not be executed

January 2011


The columns of table SYSIDX:TCREATOR CHAR(32) Creator of tableTNAME CHAR(32) Name of tableTTYPE SMALLINT Database typeINDEX_NAME CHAR(8) Name if indexINDEX_SEQS MALLINT Number of indexINDEX_FLAGS CHAR(2) Internal informationINDEX_UNIQUE CHAR(1) Flag: UNIQUE IndexINDEX_LENGTH SMALLINT Total index lengthINDEX_POSITION SMALLINT Position of indexADA_LEN SMALLINT Length (only applies to ADABAS)IMS_PSB CHAR(8) PSB (only applies to IMS)IMS_PCBNR SMALLINT PCB Number (only applies to IMS)IMS_SEGMENT CHAR(8) Segment name (only applies to IMS)COL_NAME CHAR(32) Name of columnCOL_SEQ SMALLINT Position of column in indexCOL_TYPE CHAR(8) column typeCOL_LENGTH SMALLINT Length of columnCOL_PRECISION SMALLINT Decimal digits of columnCOL_SCALE SMALLINT Fractions of columnCOL_VISIBLE CHAR(1) Flag: Column will be displayed

SELECT * FROM SYSTEM.SYSPROC;

This statement will provide an overview of all defined 'Stored Procedures'.

Columns of the SYSPROC table:PNAME CHAR(32) Name of the procedurePCREATOR CHAR(32) Creator of the procedure

SELECT * FROM SYSTEM.SYSPCOL WHERE PNAME = 'pname' AND PCREATOR = 'pcreator';

This statement provides an overview of all defined parameter for the pcreator.pname procedure. The WHERE clause is mandatory. If it is missing, the SELECT statement will not be processed.

Columns of SYSPCOL table:PCREATOR CHAR(32) Creator of the procedurePNAME CHAR(32) Name of the procedureCNAME CHAR(32) Name of parameterCTYPE CHAR(8) Parameter type (IN, INOUT, OUT)DTYPE CHAR(8) Type of data (CHAR, VARCHAR, DATE, TIME, TIMESTMP,

DECIMAL, INTEGER, SMALLINT)LENGTH SMALLINT Parameter length (number of digits or characters)PRECISION SMALLINT Number of digitsSCALE SMALLINT Number of fractions

SELECT * FROM SYSTEM.SYSSTAT;

This statement returns an overview of all information stored in the VSAM statistic file.

January 2011


Note: This table can only be used if the gathering of statistical information is activated and the transfer

medium is a VSAM file (default: TCASTAT). Columns of the SYSSTAT table: EntryLength NUM DISP(4) Length of the entry Userid CHAR(8) User name Function CHAR(32) Executed function (e.g. 'Host SQL Query') PCFileName CHAR(64) PC file name for transfer HostFileName CHAR(250) Host file name Date DATE Date of the transfer in the yyyy-mm-dd formatTime TIME End of the transfer in the hh.mm.ss formatState CHAR(16) Status of transfer (e.g. 'completed') RecordsSent NUM DISP(8) Number of records sent RecordsReceived NUM DISP(8) Number of records received BytesTransferred NUM DISP(12) Number of Bytes transferred Duration TIME Duration of transfer HostPercActive CHAR(1) Host percentage display active ('1') or '0' CRCActive CHAR(1) CRC Check active ('1') or '0'

select SYSTEM.SYSSTAT.Userid, sum(SYSTEM.SYSSTAT.BytesTransferred) from SYSTEM.SYSSTAT group by SYSTEM.SYSSTAT.Userid

This statement returns a summary table of all bytes transferred grouped by user name.

2.8.1 Table Access Sequence

Tables will be accessed in the sequence the table are defined in the FROM clause, i.e. from left to right.

A data source without an index can not be accessed directly, it is processed sequentially.

For this reason, it is recommended to position a table at the begin of a FROM clause ,which can not be accessed directly using an index. For a 'join' the first table is read only once, whereas it is necessary to access the second and each further table for every row of the first table. If the second and further table is non-indexed, it must be accessed sequentially for every row of the first table. This will considerably impact the performance.

2.8.2 Index controlled Access

The SQL Engine always attempts to access records of data sources using an index, assuming that indexed access is supported by the data source (e.g. VSAM KSDS, DL/I, etc.). Whenever an index controlled access is possible the run-time performance is improved considerably.

An index controlled access is always possible, if 1. ... no SQL functions on a key field is performed.2. ... the search items of the WHERE clause contain only constants or direct column expressions.3. ... the search conditions are defined in a way that it is possible to use an index.

January 2011


Examples:

Key fields of data source: K1,K2,K3Further data fields: D1,D2

SELECT * FROM TB1 WHERE K1 = 12 AND K2 = 14 AND K3 = 18

The complete key K1, K2 and K3 is used.

SELECT * FROM TB1 WHERE K1 = 12 AND (K2 = 14 OR K2 = 16)

The generic key K1 and K2 is used.


The generic key K1 is used.

SELECT * FROM TB1 WHERE K1 = 12 AND (D1 = 14 OR D2 = 16)

The generic key K1 is used.


There is no key to be used. The data source is read sequentially to retrieve the data (Condition 3 is not true.).

SELECT * FROM TB1 WHERE SUBSTR(K1,2) = '12'

No key is used; a function is defined for one of the key fields (The first condition is not true.).

SELECT * FROM TB1,TB2 WHERE TB1.K1 = TB2.K1+1

No key will be used since the second expression of the search condition cannot be resolved in advance (The second condition is not true.).

January 2011


2.8.1 Index controlled access for GROUP BY and ORDER BY

If the 'Group By' or 'Order By' clauses are used in a SELECT statement (also of an implied 'Group By' by using grouping functions), the SQL-Engine will always attempt to use one of the defined indexes.

The usage of indexes is only possible, if1. ... an index controlled access is supported by the data source (VSAM KSDS, DL/I, etc.).2. ... no function is applied on the respective arguments, i.e. column names only are defined.3. ... the arguments contain the sequence of key field values.4. ... in the 'Order By' clause DESC is not used.

Examples:

Key fields of data source: K1,K2,K3Additional data fields: D1,D2

SELECT * FROM TB1 ORDER BY K1,K2

No sorting necessary.

SELECT * FROM TB1 ORDER BY K1,D1

Internal sorting is necessary for D1; K1 is used.

SELECT * FROM TB1 ORDER BY D1

Internal sorting is necessary for D1.

SELECT * FROM TB1 ORDER BY K1 DESC

Internal sorting is necessary for K1.

SELECT * FROM TB1 ORDER BY SUBSTR(K1,4)

Internal sorting is necessary for the result of the function.

2.8.1.1 Performance of ORDER BY and GROUP BY

Processing data with 'Order By' and 'Group By' functions may cause considerable additional CPU load and increase input/output activities. While using these functions it should be considered that there may be an impact on system performance.

If an internal sorting is needed, the data lines are written into temporary work files using TS queues. These files are blocked to reduce the number of I/Os to a minimum. The server module generation parameter MAXSRTBS (default: 16382) determines the block size. The 'Order By' or 'Group By' sort arguments are sorted into an internal storage area. The size of this storage area is determined by the generation parameter MAXSRTBF (default: 200K). As soon as sorting is completed, the data rows are directly read from the temporary file.

January 2011


2.9 User exit for data record processing If the key word RECEXIT= was specified in the FTB, the named program will be called after each record read- and before each write-operation. For example, this program is required when records are stored in a compressed format. The program is called with the following COMMAREA using EXEC CICS LINK. The program must be linked with AMODE(31).

Field name: Type Length Description

RXCTYPE character 1 Call time:R after read operationW before write operation

RXCHFN character 64 Name of the data source (e.g.. FCT name of VSAM file)RXCHFT hexadecimal 1 Type of data source:

x'02' VSAM KSDS (FCT) x'03' VSAM ESDS (FCT)x'04' VSAM RRDS (FCT)x'05' DL/I x'06' CICS TS x'08' ADABAS x'09' MVS PDS/PS x'12' MVS VSAM KSDS (direct)x'13' MVS VSAM ESDS (direct) x'14' MVS VSAM RRDS (direct) x'15' DATACOM DB x'16' VDISK FILE x'19' VSE VSAM KSDS (direct) x'20' VSE VSAM ESDS (direct) x'21' VSE VSAM RRDS (direct)

character 2 ReservedRXCDATAD pointer 4 Address of recordRXCDATLN halfword 2 Length of data in record. If the data length changes due to

processing it must be stored in this field.RXCMXLEN halfword 2 Maximum length of data after processingRXCRETC hexadecimal 1 Return code:

0x'00' OK

All other values will be interpreted as error.RXCMRAD pointer 4 Internal useRXCHPLEN halfword 2 Length of HOSTPARM= from FTBRXCMRAD pointer 4 Address of HOSTPARM= from FTB

January 2011


2.10 User exit for SQL-Statements The system generation parameter SQLEXIT= specifies the name of a program, which can be called prior to the execution of a SQL statement. The program can either reject or modify the statement. Member TCASQLEX(.A) in the MACLIB or library is an example for this exit type. The program is called using EXEC CICS LINK with the following COMMAREA. The program must be linked with AMODE(31).

Fieldname: Type Length Description

SEXRETCD fullword 4 Return-Code: 0 OK all other values are treated as errors and processing will be terminated

SEXCMDA pointer 4 Starting address of the original SQL statementIf the modifies SQL statement is longer than the original one, you should set the starting address of the new statement

SEXCMDE pointer 4 Ending address of the original SQL-statementIf the statement has been changed in length or position, you should set the ending address of the statement.

character 4 reserved SEXMXREC fullword 4 Maximum number of rows to be returned to the client.

A value of zero (0) indicates, that all rows of the table should be returned.

SEXWORKA pointer 4 Address of a storage area (4096 bytes) which can be used for a modified statement.

January 2011


3. Calling the tcACCESS Host Server from user written programs.

The interface TCAISRV can be used to communicate with the tcACCESS host server from a user written program. The communication can be done from either CICS- or batch programs.

Because tcACCESS needs an online system to access the data, an APPC- or TCP/IP-connection to the online system must be established from a batch program.

January 2011


3.1 Calling the interface For CICS programs, the interface is module TCAISRV(.PHASE). Batch programs use TCAISRVL(.PHASE). This program also includes the connection to the online system using APPC or TCP/IP.

3.1.1 CICS In a CICS environment, the interface will be called as follows:

EXEC CICS LINK PROGRAM('TCAISRV') COMMAREA(SRVCOMM) LENGTH(nnn)

The COMMAREA has the following format: Parameter ASSEMBLER Notation COBOL Notation: Function DS CL2 PIC X(2).Traceflag DS C PIC X.Returnflag DS C PIC X.Return_Code DS F PIC S9(9) COMP. Handle DS F PIC S9(9) COMP. Server DS CL8 PIC X(8). Sysid DS CL8 PIC X(8).Userid DS CL8 PIC X(8).Password DS CL8 PIC X(8).MaxRecords DS H PIC S9(5) COMP.ParamDataLength DS H PIC S9(5) COMP.NullIndikatorFlag DS C PIX X.DescribeFlag DS C PIC X.ReturnedRecords DS H PIC S9(5) COMP.CCSIDIn DS F PIC S9(9) COMP.CCSIDOut DS F PIC S9(9) COMP.Reserved DC CL252 PIC X(252).ParamBufferLength DS F PIC S9(9) COMP.DataBufferLength DS F PIC S9(9) COMP.Parameter DS CL(n) PIC X(n). Data DS CL(n) PIC X(n).

The actual length of the COMMAREA during the execution of the LINK as well as the actual buffer length depends of the command used.

The tcACCESS Global Language Pack must be installed in order to use fields CCSIDIn and CCSIDOut.

For a detailed description about the fields refer to the section, where the parameter will be described.

January 2011


3.1.2 MVS or VSE Batch The call to the interface in a batch environment can be done in any programming language, which supports passing a pointer to the structure of the COMMAREA using register 1.The name of the interface is called TCAISRVL. This program can be statically linked to the user program, because the interface program TCAISRB is dynamically linked to during execution time. 'TCAISRVL' expects, that register 1 contains a pointer to the COMMAREA.

ASSEMBLER example:

PARMLIST DC A(COMMAREA) ... COMMAREA DS 0DFUNCTION DS CL2 TRACEFLG DS C CANRET DS C RETCODE DS F HANDLE DS F SERVER DS CL8 SYSID DS CL8 USERID DS CL8 PASSWORD DS CL8 MAXREC DS H INPDATL DS H NULLIND DS C DESCRIBE DS C RETREC DS HCCSIDIN DS FCCSIDOUT DS F DS CL252 PARMLEN DS F DATALEN DS F PARAMS DS CL(4000) DATA DS CL(16000) ... LA R1,PARMLIST L R15,=V(TCAISRVL) BALR R14,R15 ...

January 2011


COBOL example: ... 01 COMMAREA. 02 FUNKTION PIC X(2). 02 TRACEFLAG PIC X. 02 RETURNFLAG PIC X. 02 RETURN_CODE PIC S9(9) COMP. 02 HANDLE PIC S9(9) COMP. 02 SERVER PIC X(8). 02 SYSID PIC X(8). 02 USERID PIC X(8). 02 PASSWORD PIC X(8). 02 MAXRECORDS PIC S9(5) COMP. 02 PARAMDATENLÄNGE PIC S9(5) COMP. 02 NULLINDIKATORFLAG PIX X. 02 DESCRIBEFLAG PIX X. 02 RETURNEDRECORDS PIC S9(5) COMP. 02 CCSIDINPUT PIC X9(9) COMP. 02 CCSIDOUTPUT PIC X9(9) COMP. 02 RESERVIERT PIC X(252). 02 PARAMPUFFERLÄNGE PIC S9(9) COMP. 02 DATENPUFFERLÄNGE PIC S9(9) COMP. 02 PARAMETER PIC X(4000). 02 DATEN PIC X(16000). ...

CALL ‘TCAISRVL‘ USING COMMAREA. ...

January 2011


3.2 Commands to call the Host Server Module The COMMAREA described in chapter "Calling the interface" must be passed. The commands supported by the interface are summarized in the following table. Command Description DL Initiate a Download SQ Execute a SQL-Statement GN GET NEXT data records FR Terminate a process (Batch only) TR Activate a trace (Batch only) TO Deactivate a trace (Batch only)

3.2.1 'DL' command 'DL' initiates a download. The following table describes the corresponding Commarea parameter.

Field DescriptionFUNCTION 'DL' TRACEFLG Only supported in CICS environments:

'Y' indicates, that the interface should write tracing information to TS-Queue TCAISRV.CANRET Only supported in CICS environments:

‚N' returned by the interface indicates, that the calling program is not allowed to perform a task switch (no EXEC CICS RETURN). A task switch can only be performed, if the interface returns a ‚Y'.

RETCODE Return-Code of the server module.HANDLE Prior to the first call, this field must be set to zero (0). After the successful call, this must not

be changed. SERVER Name of the server module to be called.

e.g.: TCASGPFQ: VSAM-files TCASMVSQ: MVS/PDS files

SYSID CICS-environment:Name of the APPC-connection the download-request should be sent to. This parameter is optional in a CICS environment. If not used, the request will be executed locally. Batch-environment:Name of the APPC- orTCP/IP- connection the download-request should be sent to. This parameter is mandatory for a Batch-environment and specifies one of the TCACONTB- entries defined in the tcACCESS generation.

USERID User id for the tcACCESS security verification. PASSWORD Password for the tcACCESS security verificationMAXREC Maximum number of records for the download. If this parameter is 0, all records will be

downloaded. INPDATL Length of the parameter defined in field PARAMS NULLIND This field is not used.PARMLEN Length of the field PARAMS DESCRIBE N/aDATALEN Length of field DATA PARAMS Parameter for the download. Please refer to the description for program BMLDL in the

tcACCESS PC-Client manual. DATA This field is used to receive the downloaded records If the request has been started without an error, the return code field indicates zero (0) and the first data record is available in field DATA. Subsequent records can be read using the 'GN' command.

The length of the data record will be returned into field DATALEN.

January 2011


3.2.2 'SQ' command Using the ‚SQ' command, the application program can send a SQL-statement to the SQL-engine or to DB2. The following table describes the corresponding COMMAREA parameter.

Field DescriptionFUNCTION 'SQ'TRACEFLG Only supported in CICS environments:



RETCODE Return code set by the server module.X'20190000': Empty result set.

HANDLE Prior to the first call, this field must be set to zero (0). After the successful call, this must not be changed.

SERVER Name of the server module to be calledTCASTCAQ: tcACCESS SQL-Engine

TCASOSTQ: tcACCESS OST Server module TCASTCUQ: tcACCESS SQL-Engine with Global Language Pack

TCASSQLQ: DB2 Server Module TCASODCQ: ODBC Server module

SYSID CICS-environment:Name of the APPC-connection the SQL-request should be sent to. This parameter is optional in a CICS environment. If not used, the request will be executed locally. Batch-environment:Name of the APPC- or TCP/IP- connection the SQL-request should be sent to. This parameter is mandatory for a Batch-environment and specifies one of the TCACONTB- entries defined in the tcACCESS customization.

USERID User id for the tcACCESS security verification. PASSWORD Password for the tcACCESS security verificationMAXREC Maximum number of rows. If this parameter is 0, all rows will be returned. INPDATL Length of the parameter defined in field PARAMS NULLIND ‚Y' indicates, that rows of the result set should have NUL indicators.DESCRIBE If this field is ’Y’ only a description of the result-set has been requested. No data will be read.RETREC Number of records affected by an UPDATE, INSERT or DELETE statement.CCSIDIN Input CCSID of the SQL-Statements in the supplied data (field DATA).CCSIDOUT Output CCSID of character fields.PARMLEN Length of the field PARAMS DATALEN Length of field DATA PARAMS Parameter for the SQL statement. Please refer to the description for program BMLSQ in the

tcACCESS PC-Client manual. DATA This field is used to receive the result set

If the request has been started without an error, the return code field indicates zero (0) and the first row of the result set is available in field DATA. Subsequent rows of the result set can be read using the 'GN' command.

The length of the data record will be returned into field DATALEN.

January 2011


The field DATA will contain certain information, which describe each column of the result set.

Description Assembler notation COBOL notationColumn type'C' character'Z' zoned'L' float'P' packed'T' Time'D' Date'S' Timestamp

DS C PIX X.

Column length in bytes DS ZL4 PIC 9(4).Number of fractions DS ZL4 PIC 9(4).Column name DS CL30 PIX X(30).

Each column descriptions have a length of 39 bytes. Every column descriptions uses this structure.For columns of type 'VARCHAR' the length will be returned with a length of 8 bytes in field 'Column length in bytes' and 'Number of fractions' (Redefinition using ZL8 or PIC 9(8)). In case of packed decimals the “Column length in bytes” contains the precision. Floating point values are always of size 8 (double precision). The sizes of other types are fixed: date (10), time (8), timestamp (26).

Notes for Server 'TCASOSTQ':

If calls should be performed against a table that has been defined in a FTB table-definition, only 'TCASTCAQ' must be specified as the server module, if calls should be directly performed to the OST Server (TCAOSTQ) for example UPDATE statements, the parameter defined in the FTB of the SQL-Engine must also be specified in the calling program. These parameter are:

TY= Access type (ODBC,UDB,OCI)TO= TimeoutIP= Address and port of the OST Server ( 'address:port' )CS= Connection string

Alternatively to parameter CS, TY and IP parameter 'OS=' can be used. This one uses a server that has been defined in macro 'TCAOSRVT' .

If parameter in addition to the 'OS=' have been specified, the values from these parameter overwrite the values defined in the macro.

3.2.3 'GN' command The 'GN' command request then next record from a ‚DL' command or the next row from a ‚SQ' command.

Field Description FUNCTION 'GN' TRACEFLG Only supported in CICS environments:



RETCODE Return code of server module X'20190000': if DATALEN > 0: End of data, this record is the last record.

if DATALEN = 0: End of data, no further records available. HANDLE This field must not be changed SERVER n/aSYSID n/aUSERID n/aPASSWORD n/a

January 2011


MAXREC n/aINPDATL n/aNULLIND n/aDESCRIBE n/aPARMLEN Length of field PARAMS DATALEN Defined length of field DATA. This field is used by the interface to return the length of the

data. It must be set prior to every new call. PARAMS n/aDATA This field is used to receive the data. If data records requested by a ‚DL' command are processed, field DATA contains the current data record. Field DATALEN contains the length of the data record.

If a result set requested by a 'SQ' command is processed, field DATA contains the result set columns as described by the 'SQ' command. The sum equal to all column lengths will be returned in field DATALEN.

If field NULLIND was set to 'Y' for a ‚SQ' command, each column will have the null indicator in front of the actual data. The null indicator is a 2 byte binary field (Assembler DS H; COBOL PIC S9(4) COMP). A value of greater than 0 indicates, that the column contains NULL information. The null indicator expands each column by 2 bytes.

3.2.4 'TE' command The 'TE' command terminates processing before End-of-data is reached. In a batch environment the online connection is also closed.

The last command in a program sequence must be the "TE" command, that frees all allocated storage areas. This relates to both the Batch- as well as the CICS-interface. In the case of the Batch-interface, the "TE" command will also terminate the communication to the Online-system.

Field DescriptionFUNCTION 'TE'TRACEFLG Only supported in CICS environments:

'Y' indicates, that the interface should write tracing information to TS-Queue TCAISRV.CANRET n/aRETCODE Return code of the server module. HANDLE This field must not be changed. SERVER n/aSYSID n/aUSERID n/aPASSWORD n/aMAXREC n/aINPDATL n/aNULLIND n/aDESCRIBE n/aPARMLEN n/aDATALEN n/aPARAMS n/aDATA n/a

3.2.5 'FR' command The 'FR' command terminates processing before End-of-data is reached in a batch environment without closing the connection to the online system. This command is not available in an online environment.

January 2011


Field DescriptionFUNCTION 'FR'TRACEFLG n/aCANRET n/aRETCODE Return code of the server module. HANDLE This field must not be changed. SERVER n/aSYSID n/aUSERID n/aPASSWORD n/aMAXREC n/aINPDATL n/aNULLIND n/aDESCRIBE n/aPARMLEN n/aDATALEN n/aPARAMS n/aDATA n/a

3.2.6 The Command 'TR' Using the command 'TR' a trace can be created in a batch environment. This command is not available in an online environment. Tracing for the online environment is controlled by the tcACCESS generation-parameter TRACE=.

Field DescriptionFUNCTION 'TR'TRACEFLG Field is not used.CANRET Field is not used. RETCODE Field is not used. HANDLE Do not MODIFY this field. SERVER Field is not used. SYSID Field is not used. USERID Field is not used. PASSWORD Field is not used. MAXREC Field is not used. INPDATL In aVSE-environment, the trace can only be displayed on the system-console. Field INPDATL

must have a value of 0.

In an OS/390-environment the trace can either be written to the system-console (INPDATL=0) or into a separate output file (INPDATL=8). The name of the DD-statements for this file must be specified in the PARAMS field (i.e. TCATRACE). The JCL-statement for the file could look like:

TCATRACE DD SYSOUT=*

NULLIND Field is not used. DESCRIBE Field is not used. PARMLEN Defined length of field PARAMS DATALEN Field is not used. PARAMS Refer to field INPDATLDATA Field is not used.

3.2.7 The Command 'TO'

January 2011


Using the command 'TO' you can deactivate the trace in a batch environment. This command is not available in an online environment. Tracing for the online environment is controlled by the tcACCESS generation-parameter TRACE=.

3.2.7.1 Return codes of the interface After returning from the interface, field 'RETCODE' is set. The tcACCESS server modules set the return code.

If RETCODE contains zero the call was successful and processing can continue. If a return code not equal zero was set than EOD (end-of-data) was encountered or an error has occurred; no further 'GN' commands must be issued. A 'TE' (CICS) or 'FR' (Batch) command is not necessary after a return code not equal to zero was returned.

A complete description of all return codes and their descriptions is available in file ENGLISH.ERR . You can locate this file in the \LNG subdirectory of the tcACCESS PC installation.

January 2011


3.3 Calling the batch interface using 'TCASRVUP' The utility program 'TCASRVUP' is available to use all the functions of the batch interface without having to develop your own programs. 'TCASRVUP' can be executed using the following JCL: //RUNISRV JOB ,'RUN THE SRV PGM',CLASS=A,MSGCLASS=S //STEP1 EXEC PGM=TCASRVUP,REGION=0M //STEPLIB DD DISP=SHR,DSN=tcaccess.v800.loadlib //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * ... Commands ...

Abb. 1: Sample job TCASRVUP for OS/390

// JOB RUNISRV// LIBDEF *,SEARCH=(bos.tcaccess) // EXEC TCASRVUP,SIZE=AUTO ... Commands... /*/&

Abb. 2: Sample job TCASRVUP for VSE

'TCASRVUP' accepts the following commands: APOST Use a ' to delimit character stringsCHECK Wait, until a certain time is reached.CONNECT Connection to an online system.CCSID Specification of translation options when Global Language Pack is installedDB2CHAR Prepare floating point values in SQL queryDECR Decrement a variable by a specified value.DEF Declare a variableDESCRIBE Only request description of result set with EXECSQLDOWNLOAD Start a downloadEXECSQL Execute a SQL statementEXIT Terminate processing.GEN DATALOAD Generate a VSE DB/2 DATALOAD command based on a SQL statementGEN LOAD Generate an OS/390 DB/2 LOAD command based on a SQL statementGOTO 'GOTO' a label.HOSTPARMS Parameter that should be passed to the server moduleHOSTPARMSADD

Parameter that should be passed to the server module (continuation line)

IF Condition.INCR Increment a variable by a specified value.MAXREC Maximum number of records/rowsMODULE Name of the server module to be calledNULLS Flag to specify, whether a null indicator should be usedNUM2ZONE Editing of numeric values returned from a SQL statement

January 2011


NUMEDIT Editing of numeric values returned from a SQL statementONERROR Processing of error conditionsOUTFILE Name of the DD/DLBL- JCL statement where the returned data should be stored.PAUSE Pause processing for a given time intervalPARAMETER Parameter for the server modulePUNCH Write text to SYSOUT/Punch-QueueQUOTE Use a " to delimit character stringsTIMESTAMP Generation of time stamps in the output listing.WAITC Wait until a certain time is reached.WTO Write messages to the console

3.3.1 APOST

The 'QUOTE' command uses a quote (") to delimit character strings. Using ‚APOST' will use an apostrophe (') as delimiter.

APOST

3.3.2 CHECK The 'CHECK' command waits for a defined time period. Different to the 'WAITC' command, processing with the next parameter will immediately continue, if the specified time has passed by. Example: CHECK 04:50:00

3.3.3 CONNECT The ‚CONNECT' command is used to establish a connection to a tcACCESS online system. Using this connection. Using this connection task processing with a PC client can be started. Connections to an online system must be defined at system generation. Detailed information can be found in manual "tcACCESS Customization”, Chapter "Batch accesses to the online system”. Connections are defined using macro TCACONTB.

Example: CONNECT DBDCCICS

3.3.4 CSID Command ‘CCSID’ can be used to specify the translation options for the input and output of SQL commands when the tcACCESS Global Language Pack is installed.

January 2011


“CSSID IN“ specifies the CCSID that should be used to interpret the SQL statement, “CCSID OUT“ specifies the CCSID that should be used to process the output. If no “CCSID OUT“ has been specified the CCSID of “CCSID IN” is used..

To use the tcACCESS Global Language Packs the server that must be called (command MODULE) must be „TCASTCUQ“.

Example: MODULE TCASTCUQ CCSID IN 37 CCSID OUT 1208

3.3.5 DBL2CHAR Starting with this command all following floating point values of a result set will be written to the output file in exponential format.

DBL2CHAR YES

3.3.6 DECR The 'DECR' command decrements a value of a variable. No specification uses a decrement value of 1.

Examples: DECR COUNTER DECR COUNTER 10

3.3.7 DEF The 'DEF' command declares a numeric variable. An initial value can be defined during the declaration. If nothing is specified, the variables will be initialized to (Zero).

Examples: DEF COUNTER DEF EIGHT 8

3.3.8 DESCRIBE

January 2011


This command controls, that only the result set-descriptions will be returned for the fSQL-statements that follow. If DESCRIBE has been set, no data access will be performed by the SQL-statements.

Example: DESCRIBE

3.3.9 DOWNLOAD

'DOWNLOAD' initiates a download using parameter which have been defined before this command.

Example:

DOWNLOAD

January 2011


3.3.10 EXECSQL

Executes a SQL statement using previously defined parameter.

Place the SQL statement you want to execute on the next lines following EXECSQL. The parser treats all lines as SQL statements until it reads '$$$END' starting at column 1.

Example: EXECSQL SELECT * FROM DEMO.ARTIKEL WHERE NR = 4711 $$$END

3.3.11 EXIT 'EXIT' terminates the processing. You can specify a numeric return code for the job step. If no return code is specified, a return code, which has already been set, remains unchanged. Example: EXIT 12

3.3.12 GEN DATALOAD

If this command is specified prior to an EXECSQL command, a DATALOAD control statement will be generated for the VSE DB/2 Load utility. Unless the 'PUNCH' parameter is used, the DATALOAD statement will be written to the output report. If a PUNCH parameter is specified, the generated DATALOAD statement will be written to the PUNCH-queue.

Example:

GEN DATALOAD creator.table GEN DATALOAD creator.table PUNCH

For every column a TCI statement will be generated in the following format:

Field name Start-End Type NULL POS(Start-1)='N'

For DB/2 fields, which have been defined as 'NOT NULL', the NULL clause (NULL POS(nnn) = 'N') will result in syntax errors when executing the DB/2 Load Utility. The generated DATALOAD statement must be edited.

January 2011


3.3.13 GEN LOAD

If this command is specified prior to an EXECSQL command, a LOAD control statement will be generated for the OS/390 DB/2 Load utility. Unless the 'PUNCH' parameter is used, the LOAD statement will be written to the output report. If a PUNCH parameter is specified, the generated LOAD statement will be copied to SYSOUT.

Example:

GEN LOAD creator.table GEN LOAD creator.table PUNCH

For every column of the result set a line in the following format will be generated:

Field name POSITION(Start:End) Type NULLIF(Start-1:Start-1) = 'N'

The NULL clause will only be generated, if the ‚NULLS' command has been activated-

For DB/2 fields, which have been defined as 'NOT NULL', the NULL clause (NULLIF(n:n) = 'N') will result in syntax errors when executing the DB/2 Load Utility. The generated DATALOAD statement must be edited.

3.3.14 GOTO The 'GOTO' command continues processing at another position within the parameter stream. Branching to a specified label can take place. These labels must be indicated by a dot (.) at the first position. When branching to a label, the dot can be omitted.

Example: GOTO LABEL ... .LABEL

3.3.15 HOSTPARMS

The ‘HOSTPARMS’ command specifies the parameter that are to be passed to the Host Server Module. Example: CS=DSN=dsnname;TN=TCASODCQ;UID=xxxx

3.3.16 HOSTPARMS ADD Command ‘HOSTPARMS ADD’ indicates the parameters supplied to a host server module are distributed on continuation lines.

January 2011


Example: HOSTPARMS CS=HOST=AXEL2;PORT=50000; HOSTPARMS ADD DATABASE=SAMPLE;UID=DB2INST1; HOSTPARMS ADD PWD=DB2INST1;TRACE=N;, HOSTPARMS ADD TN=DEFAULT,

3.3.17 IF The 'IF' command defines conditions for processing. A condition can be the comparison of a variable and a numeric constant. The following comparison operators are supported:

'='...................equal '>='................greater or equal'<='................less or equal'>'...................greater '<'...................less '<>'................not equal to

After the condition, a label is defined where processing will continue, if the condition results in 'true'. If the condition is 'false', processing will be continued with the next parameter following the 'IF' parameter.

Example: IF COUNTER1 < 3 LOOP1 IF I > 67678 MARKE

3.3.18 INCR The 'INCR' command increments the value in a declared variable. It is possible to define the value, which should be use to increment, the defined variable. If nothing has been specified the increment value will be 1 (one).

Examples: INCR COUNTER INCR COUNTER 10

3.3.19 MAXREC

Using this command the maximum number of data records loaded can be specified. If not specified, zero (0) will be assumed and all data records will be processed. Example: MAXREC 100

3.3.20 MODULE

January 2011


This command specifies the name of the serve module to be called.

Examples: tcACCESS SQL-Engine: MODULE TCASTCAQ tcACCESS SQL-Engine Global Language Pack: MODULE TCASTCUQ DB/2 Server Module: MODULE TCASSQLQ ODBC Server Module: MODULE TCASODCQ MVS/PDS Download: MODULE TCASMVSQ VSAM files, TS-Queues: MODULE TCASGPFQ ODBC Modul: MODULE TCASODCQ

3.3.21 NULLS

This command controls the creation of null indicators for a result set, which has been created using a SAL statement. The null indicator precedes the filed content as represents a ‚N' for NULL or a space for not NULL. If NULLS has been specified, the generated DATALOAD/LOAD statement will have a corresponding NULL clause.

Examples: NULLS YES NULLS NO

3.3.22 NUM2ZONE

Using this command, numeric values of a result set will be written to the output file as numeric digits (0...9).

Example: NUM2ZONE YES

The single use of this command only makes sense if you do not expect any negative values (refer to NUMEDIT).

3.3.23 NUMEDIT

If NUM2ZONE YES has been specified, the NUMEDIT command will result in creating signs and – optionally – decimal points.

Example:

NUMEDIT YES

January 2011


3.3.24 ONERROR The 'ONERROR' command evaluates error condition. The following syntax is valid: ONERROR [error code] GOTO | RESUME | EXIT | CCODE [label|code]

ONERROR RESUME The 'RESUME' parameter indicates that the internal error handling for calls to the interface is deactivated. Processing is not terminated with an error message when an error occurs during the call but the error message is returned. It can be interrogated with the 'ONERROR …' command.

ONERROR GOTO This parameter performs a conditional branch. A 'label' must be defined. If the error code is set, processing will be continued with the command following the label. If the interrogated error code is not set, processing is continued with the command following the 'ONERROR' statement.

ONERROR EXIT The 'EXIT' parameter will end processing. If a condition code is defined after the EXIT keyword, it will be changed.

ONERROR CCODE The 'CCODE' parameter sets a condition code; however, processing will not be terminated. This allows the definition of sequences like 'Set condition code, create a message and terminate'.

Note: If the 'error code' is not set, it will be checked for 'not equal to '. This means that an 'ONERROR

EXIT' statement will terminate processing, if the error code is not equal to . Examples: ONERROR RESUME ... ONERROR 20B00021 GOTO .TESTCOUNT ONERROR 08150815 GOTO .RET15 ONERROR CCODE 99 ONERROR EXIT 12

3.3.25 OUTFILE

This command defines the name of a DD- or DLBL JCL-statement. This statement defines the file, the result will be written to. If no OUTFILE command has been specified or the command SYSPRINT has been used, the first 132 characters of the result will be printed.

VSE only:The SYSPUNCH parameter will redirect the data to the POWER Punch queue. The DATALOAD records will be automatically written in the correct format.

Examples: OUTFILE LOAD OUTFILE SYSPUNCH

If the output should be written to a VSE SD file, use the following JCL to define the file.

January 2011


// DLBL LOAD,'DB2.LOAD',0 // EXTENT SYS010,volser,1,0,nnnn,mmmm // ASSGN SYS010,FBAV,VOL=volser,SHR

If the output should be written to an OS/390 file, use the following JCL to define the file:

//LOAD DD DSN=…,DISP=(NEW,CATLG),VOL=SER=…,UNIT=…

3.3.26 PARAMETER

PARAMETER defines the calling parameter to the corresponding host server modules. Refer to a detailed description to the tcACCESS PC-client manual, discussing the BMLDL program.

Example: PARAMETER HF=queue name(TS)

3.3.27 PUNCH

The specified parameter of the PUNCH command will be written to the POWER-Punch queue or SYSOUT.

Example: PUNCH 'CONNECT SQLDBA IDENTIFIED BY SQLDBAPW; '

3.3.28 PAUSE The 'PAUSE' command defines a wait time. Processing will be delayed until this time has passed. Then processing will be continued with the next parameter. The wait time can be defined in seconds or minutes by using the parameter 'S' (seconds) or 'M' (minutes). Examples: PAUSE 10 SEC PAUSE 5 MIN

3.3.29 TIMESTAMP The 'TIMESTAMP' command defines, that a timestamp of the execution time should be printed in the output report. It is possible to specify either 'ON' or 'OFF' as a parameter.

January 2011


Examples: TIMESTAMP ON TIMESTAMP OFF

3.3.30 QUOTE

The default delimit character for character strings containing spaces is the apostrophe ('). The QUOTE command changes this to quotes ("). Using the APOST command will switch back to an apostrophe.

QUOTE

3.3.31 WAITC The 'WAITC' command waits until the defined time has been reached. Different to the 'CHECK' command it will wait for this time until the next day, when the specified time has already passed by on this day. Example: WAITC 04:50:00

3.3.32 WTO The 'WTO' command writes a defined message on the system console or into the job log. It is possible to specify an optional message. The '&MSG' variable issues the message which was the last one sent by the PC. Example: WTO 'Processing is continued.' WTO &MSG

January 2011


3.4 Access types of Server ″TCASOSTQ″

Multiple access types are available to access Open System Transparency data. These access types differ because of their flexibility and performance.

In the following chapters these access types are described and their individual advantages are highlighted. Each chapter also contains an example that shows how the access type can be tested using the batch utility TCASRVUP.

3.4.1 Access using the tcACCESS SQL-Engine

The standard access path uses a table defined to the tcACCESS SQL-Engine. The table looks like a table representing a mainframe data source.

Using this type of access the syntax of the tcACCESS SQL-Engine will be used. It is possible to join data obtained from Open System Transparency data sources with mainframe data. This access type is the most flexible.

Using this constellation no write access is possible to the Open System Transparency tables.

No additional parameter are required when using the query from the tcACCESS front-end or from a Batch-region or partition. All required parameter are part of the table definition.

The connection from a batch region to the online system is established via APPC or TCP/IP. This is specified in the TCACONTB macro of the system customization..

Example:

(a) Customization

* TCACONTB TYPE=INIT TCACONTB TYPE=ENTRY,NAME=CICS,CONNECT=TCPIP,IPPORT=3040 TCACONTB TYPE=FINAL *

January 2011


* TCAOSRVT TYPE=INIT TCAOSRVT TYPE=ENTRY,NAME=LINUXSERV_ODBC,IPADDR=linserv, * IPPORT=3020,CONNSTR='DSN=TCAIX;',ACCESS=ODBC TCAOSRVT TYPE=FINAL *

(b) Table definition (/TABLES/OST/AIXARTICLE.FTB)

** SQL-Engine table definition file (FTB format)* #############################################*HOSTFILE=XXX(ODBC)**OSTSERVER=LINUXSERV_ODBCTIMEOUT=30SQL_SELECT=SELECT *SQL_FROM=FROM DEMO.ARTICLE

(c) Execution

//TCASQL1 JOB ,'RUN THE SRV U PGM',CLASS=A,MSGCLASS=A //* //STEPODBC EXEC PGM=TCASRVUP,REGION=0M //STEPLIB DD DISP=SHR,DSN=tcaccess.loadlib//SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * * CONNECT CICS USERID USERIDPASSWORD ******MODULE TCASTCAQ EXECSQL SELECT * FROM OST.AIXARTICLE$$$END

3.4.2 Access to the Server in an Online System

If a WRITE access to a source controlled by the tcACCESS Open System Transparency component is required, the OST-Server must be directly addressed.

January 2011


The communication is established in the same ways as described in the previous chapter from a batch region to the online system and from there to the OST-Server. For this request type the corresponding server TCASOSTQ must be defined in the extended host parameter.

In addition to the server specification the definition of the connection type to the server is important. The defined OSTSERVER in macro TCAOSRVT or the direct specification of the server in the extended host parameter can be used.

The syntax of the query must be conform to the syntax requirements of the target database. The query is directly sent to the Open System Transparency Server.

Example:

(a) Customization

* TCACONTB TYPE=INIT TCACONTB TYPE=ENTRY,NAME=CICS,CONNECT=TCPIP,IPPORT=3040 TCACONTB TYPE=FINAL *

* TCAOSRVT TYPE=INIT TCAOSRVT TYPE=ENTRY,NAME=LINUXSERV_ODBC,IPADDR=linserv, * IPPORT=3020,CONNSTR='DSN=TCAIX;',ACCESS=ODBC TCAOSRVT TYPE=FINAL *

(b) Execution

//TCAINSRT JOB ,'RUN THE SRV U PGM',CLASS=A,MSGCLASS=A //STEPODBC EXEC PGM=TCASRVUP,REGION=0M //STEPLIB DD DISP=SHR,DSN=tcaccess.loadlib//SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * * CONNECT CICS

January 2011


USERID USERIDPASSWORD ******MODULE TCASOSTQ HOSTPARMS OS=LINUXSERV_ODBC EXECSQL INSERT INTO DEMO.ARTICLE ( NR, NAME) VALUES ( 887, 'NEW ODBC RECORD');$$$END

3.4.3 Direct access to the OST Server

If the online system is not available, a batch region can directly communicate with the OST-Server on a workstation. READ and WRITE access is supported.

A connection to the OST Server on a workstation can be performed in two different ways.

(1) Connection using a OST-Server definition (macro: TCAOSRVT)

For this access type (available as of tcACCESS version 8 Rev. 408) all information relevant to the processing (i.e. IP-address of the workstation OST Server, connection string) are defined as part of the OST Server definition (macro: TCAOSRVT) of the tcACCESS customization.

Example:

TCAOSRVT TYPE=INIT TCAOSRVT TYPE=ENTRY,NAME=XPSERVER, * IPADDR=xpserv.bos.net,IPPORT=3020,ACCESS=ODBC, * CONNSTR='DSN=UDBAIX;UID=db2inst1;PWD=password;' TCAOSRVT TYPE=FINAL

The calling program uses the host parameter OS= to supply the name of the OST Server. Parameter CONNECT or SYSID are not required because NO connection to the online system is required.

Example:

January 2011


//TCASRVD JOB ,'RUN THE SRV U PGM',CLASS=A,MSGCLASS=A //* //STEPODBC EXEC PGM=TCASRVUP,REGION=0M //STEPLIB DD DISP=SHR,DSN=tcaccess.loadlib//SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * * MODULE TCASOSTQ HOSTPARMS OS=XPSERVEREXECSQL SELECT * FROM DEMO.ARTICLE WHERE NR < 100 $$$END

(2) Dynamic specification of the connection string

For this type of access the server that should be connected must be defined as part of the tcACCESS customization (macro: TCACONTB). All required parameter (connection string, access type, timeout, etc.) must be supplied as parameter in the calling program.

Example:

(a) Customization

* TCACONTB TYPE=INIT TCACONTB TYPE=ENTRY,NAME=LINUX_SERV,CONNECT=TCPIP, * IPPORT=3020,IPADDR=linserv TCACONTB TYPE=FINAL *

(b) Execution

//TCASRVD JOB ,'RUN THE SRV U PGM',CLASS=A,MSGCLASS=A //* //STEPODBC EXEC PGM=TCASRVUP,REGION=0M //STEPLIB DD DISP=SHR,DSN=tcaccess.loadlib//SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * * CONNECT LINUX_SERVMODULE TCASOSTQ HOSTPARMS CS=DSN=TCAIX;,TY=ODBC,

EXECSQL SELECT * FROM DEMO.ARTICLE WHERE NR < 100 $$$END

January 2011


4. tcACCESS Virtual Disks

Virtual disks allow to provide host disk space for PC clients in a way which makes it possible for them to access this space like any PC disk (e.g. DIR, CD, COPY, etc.). This function offers the possibility to connect PCs, which are connected with the host, although they are not directly connected between each other's via a network.

This tcACCESS version includes an optimized virtual disk facility. A file concept has been designed which provides better performance due to an optimization of the read and write accesses as well as the implementation of caching functions. Additionally, it is now possible to use file names, which may be up to 255, characters long in order to correspond with the file naming conventions on the PC.

The interface offers new functions to access data on the Virtual disks from a host based program. The interface provided up to Version 3.0.x can still be used.

4.1 tcACCESS Virtual Disks - Online Processing Following functions are provided to process virtual disks within the online system

a) FDISK - Partition administration andb) SHELL - Command input

These functions are called via the 'VDisk Maint.' tab within the tcACCESS monitor system or via the 'FDIS' and 'SHEL' transactions in a CICS system.

4.1.1 Partition Administration in an Online System After entering the 'FDIS' transaction or starting the partition administration from within the tcACCESS monitor system the partition administration will become active. The file displayed at the beginning is always the file which contains the data to control the SQL Engine. The following screen will be displayed.

tcACCESS V8.0.0 Virtual Disk FDISK Interface 20.03.2007 16:14:08 Message: User: CICSUSER Command => __________________________________________ Applid: CICS File: TCAVDI Access: W Column "F" supports the following partition functions: C Create D Delete U Undelete I Inact. A Activ. R Release V View Entry 1 - 4 of 4 Capacity Used Storage Number F Name Byte MB Byte MB Perc. Entries State . SYSDSK 1081080 1.031 40413 0.039 4% 7 OK . DISK1 1081080 1.031 32829 0.031 3% 0 OK . DISK2 1081080 1.031 32829 0.031 3% 0 OK . DISK3 1081080 1.031 32829 0.031 3% 0 OK _______________________________________________________________________________ PF3 Exit PF5 Refresh PF9 Display +

Fig. 3: Partition Administration in an Online System

Function key assignment: PF3 End partition administration PF7 If this key is displayed, use it to page backwards. PF8 If this key is displayed, use it to page forwards. PF9 The display switches between the first and the second part of data provided for a partition.

January 2011


Field description: entry n - n of nnn

Number of partitions on the current virtual disk and start and end position of this display page within the partition table.

F Selection field for one of the functions listed in the header line. Name Name of the partition. Capacity The capacity of a partition is defined in Bytes and Megabytes. For the calculation of Megabytes

the following formula is applicable: 1 MB = (1024 * 1024) Bytes. Occupied storage

The storage used for data and directory entries is shown in Bytes, Megabytes and proportional to the entire size of the partition.

No. of entries

This field shows the number of directory entries in the partition. Status The status field of the partition can contain one of the following values:

'OK' The partition is active and online.'EMPTY' The partition is empty and can be used for a new partition.'DELETED' The partition was deleted and can be restored using the 'U' function.'INACTIVE' The partition was set to 'inactive'.'PENDING' The partition is currently processed (e.g. formatted).'READ ERROR' A read error has occurred on this partition.

S-Rec The first record of the partition is displayed. It is shown in hexadecimal characters. E-Rec The last record of the partition is displayed. It is shown in hexadecimal characters. defined This column shows creation date and time as well as the name of the creator. Function selection: The 'F' field allows to enter a function listed in the header line.

C Create The 'Create' function allows to define a new partition on the virtual disk. The partition name must not contain any blanks. Note: If a partition is not already created on a virtual disk, there will be no line for function input. In this

case it is possible to create a first partition with the 'NEWPART' command.

D Delete The 'Delete' function allows to remove a partition from a virtual disk. The status of the partition switches to 'DELETED' and can be restored via the 'U' function.

U Undelete A deleted partition can be restored via the 'U' function. Its status changes from 'DELETED' into 'OK'. The 'U' function is only available for deleted partitions.

I Inactivate

January 2011


In order to temporarily reject access to a partition the 'I' function is provided. This function puts the partition in the 'INACTIVE' status. It is only valid for partitions with an 'OK' status.

A Activate If a partition has been set inactive by using the 'I' function, the 'A' can be used to reset this operation. The 'A' function resets the status of a partition to 'OK'. This partition can then be accessed again. This function is only applicable for partitions with the 'INACTIVE' status.

R Release If the 'D' function has been performed to set a partition inactive, then the 'R' function can be used to release the disk space which is used by this partition. The 'R' function sets partition into the status 'EMPTY'. This partition can not be restored with the 'U' function. It is only valid for partitions with 'DELETED' status.

V View The 'V' function changes to an input request. This input request is described in detail in chapter "Command linein an Online System". It is only valid for partitions with an 'OK' status. Command: The 'Command =>' line allows to enter commands. The following commands are possible:

NEWPART Create a new partition The 'NEWPART' command is identical with the 'C' function which allows to create a new partition. If no partition is defined yet, this command can be applied to create the first partition.

FILE Switch file The 'FILE' command allows to switch to a new basic file. Then this file is displayed as current file in the overview. The partitions of this file will be displayed. Note: If an VDISK error (error number starts with '22') occurs, the display of the partitions will be reset.

After pressing the 'PF5' key the display will be restored.

4.1.2 Command line in an Online System For accesses to files in an online system a interface is provided which is similar to a PC DOS input request. The command line prompt is displayed:

a) by calling the 'SHELL' function from the 'VDisk Maint.' tab of the tcACCESS monitor systemb) via the 'V' function from the partition administrationc) by calling the 'SHEL' transaction within CICS.

The input request starts with the partition which contains the information to control the tcACCESS SQL Engine. The following screen will be displayed:

January 2011


tcACCESS V8.0.0 Virtual Disk SHELL Interface 20.02.2007 16:16:35 Message: User : CICSUSER ---------------------------------------------------------\ Applid: CICS | File: TCAVDI | Partition: SYSDSK \--------------------- tcACCESS Virtual Disk Interface ready. /> ____________________________________________________________________________ _______________________________________________________________________________ PF3 Exit PF8 Forward

Fig. 4: Command line in an Online System

In the upper part of the screen status information is displayed. The 'Message:' field is used for messages, error codes, etc.

The separation character for directories is not the backslash as used in PC DOS but the '/' character. The usage of capital and small letters is not important.

Function key assignment:

PF3 End the input request

PF4 'Cancel' key for commands which process several inputs and outputs (e.g.: 'dir' across several screens, 'copy con', etc.)

The command line accepts the following commands: CD The 'CD' command to change to another work directory. The superior directory is addressed with

'..' and the subordinated directory with its name. If changing between several directories is wanted, the directory names must be separated from each other with the separation character '/'. Directories names containing blanks can be enclosed in quotes.

Example:

CD .. change to the next higher directoryCD system/tables change from the main directory to the TABLES/SYSTEM directory.

CLS The 'CLS' command will clear the working section. COPY CON The 'COPY CON' command allows to enter a text file. The text file is specified line per line;

pressing PF4 ends the input mode. The entered text is converted into the ASCII character set and then saved in a file. For the translation the code page defined in the system generation will be applied. Any entered small characters will not be converted into capital characters.

DEL The 'DEL' command deletes the specified file. A generic delete can be performed by entering

generic file names.

Example: DEL *.* deletes all files in the current directoryDEL file* deletes all files in the current directory with a name starting with 'file'.

EXIT The 'EXIT' command ends the command line and has the same effect as pressing the PF3 function

key.

January 2011


FDISK The 'FDISK' command activates the partition administration. The partition administration is called for the file which is the current file in use by the command line.

FILE The 'FILE' command changes to another file. It is attempted to access the partition which has been

the current partition before the switch. If a partition with this name does not exist, the error message 'RC=221D0000 is displayed: 'Partition does not exist'. You then should switch to a valid partition within this file by using the 'PART' command.

MD The 'MD' command allows to create directories. Directory names with blanks can be enclosed in

quotes. PART The 'PART' command allows to switch to another partition on the current file. The new partition

name must be specified as parameter for this command. RD The 'RD' command allows to delete directories. It is only possible to delete empty directories.

Directory names with blanks should not to be enclosed in quotes. RENAME The 'RENAME' command allows to rename a file or a directory. Directory or file names with

blanks must be enclosed in quotes. RESET The 'RESET' command allows to reset a file. Thus, an existing 'OPEN' attribute will be deleted for

the file. TYPE The 'TYPE' command allows to edit a text file on the screen. Pressing the 'Enter' key will continue

output, if the file exceeds a screen page. The output can be terminated by pressing the 'PF4' key. 4.2 tcACCESS Virtual Disks - Batch Utility Program A batch program with a wide range of functions is provided to maintain the virtual disks using batch processes. 'TCAVDIUP' is the program to be called for maintaining the virtual disk in batch. It supports the following functions: Function DescriptionBACKUP Save the files and directories on a virtual disk including the migration of formats until

version 3.0.xCD Navigate the directoriesCONNECT Establish connection with CICS or the tcACCESS Monitor system for processing the

supplied commands within CICS or the tcACCESS Monitor system. Batch programs do not need to open and use the file directly, this is done via the tcACCESS CICS or Monitor system. For the definition of the connections, the "TCACONTB" macro needs to be integrated in the system customization.

COPY CON Create a file from the input dataDIR List all directories within the pathDIR -s List all directories within a path including all files and subdirectoriesFDISK ACTP Activate a partitionFDISK DELP Delete a partitionFDISK DIRP List all partitions of a virtual diskFDISK FORM Format a virtual diskFDISK FREP Release space of a deleted partitionFDISK INAP Inactivate a partitionFDISK UNDP Restore a deleted partitionFILE Switch between basic filesMD Create a directoryMODE Determine the access mode for the basic filePART Switch between partitions of a virtual diskPWD Password

January 2011


RD Delete a directory RENAME Rename a directory entryRESTORE Restore the files and directories of a virtual disk from the BACKUPTRUNCATE Activate/Deactivate Function "Truncate Trailing Blanks" for COPY CON TYPE Print the content of a file USER UserID //RUNVDI JOB ,'RUN THE VDI U PGM',CLASS=A,MSGCLASS=S //STEP1 EXEC PGM=TCAVDIUP,REGION=0M //STEPLIB DD DISP=SHR,DSN=tcaccess.v800.loadlib //TCAVDI DD DISP=SHR,DSN=tcaccess.v800.TCAVDI.RRDS//BACKUP DD DISP=(,CATLG),DSN=tcaccess.backup.file, // VOL=SER=volser,UNIT=unit,SPACE=(CYL,(n,n)) //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * ... Parameter statements *

Fig. 5: Example job for Batch processing of Virtual disk - OS/390

// JOB RUNVDI// LIBDEF *,SEARCH=(bos.tcaccess) // DLBL TCAVDI,'tcaccess.v800.TCAVDI.RRDS',,VSAM,CAT=catalog // ASSGN SYS010,DISK,VOL=volser,SHR // DLBL BACKUP,'tcaccess.backup.file',0,SD // EXTENT SYS010,SYSWK1,1,0,nnnnn,nnnnn// EXEC TCAVDIUP,SIZE=AUTO ... Parameter statements /* /&

Fig. 6: >Example job for Batch processing of Virtual disk - VSE

4.2.1 BACKUP The BACKUP parameter allows to write files of the defined disk into a backup. The following syntax applies: BACKUP [-ASRWD] [Filter]

The file for the backup must have a corresponding DD statement or a 'BACKUP' DLBL statement. A DCB can be defined as follows:

January 2011


DCB=(RECFM=V,LRECL=32004,BLKSIZE=32008

The 'BACKUP' command can be used with the following parameter. The parameter must always be specified in front of the filter.

-S Subdirectories will also be saved. -A Files with an archive attribute only will be saved. -R The archive attribute is reset after the file has been successfully saved.-W The tape is rewound after the save operation has been successfully completed (VSE only). This

parameter cannot be used in conjunction with the -D parameter.-D VSE only. Backup is performed to a disk file instead of a tape (This parameter cannot be used in

conjunction with the -W parameter. The 'BACKUP' command accepts filter options to determine the files to be saved. These filters should be defined in the following way: BACKUP SYSTEM

All files in the 'SYSTEM' subdirectory should be saved. BACKUP *.VTB

Files matching the '*.VTB' filter should be saved. If no filter is defined, then '*.*' will be assumed. Example: FILE TCAVDI PART SYSDSK MODE R CD TABLES BACKUP -S *.VTB

All SQL Engine VIEWS for all creators should be saved.

4.2.2 CD The CD parameter switches to another directory. The following syntax applies to the 'CD' command: CD [.. | directory name]

Several directories can be defined. They must be separated using a '/'. The main directory is specified with '/'. Example: CD TABLES/SYSTEM CD ..

January 2011


CD /

4.2.3 CONNECT To eliminate the need to close a virtual disk in the online system where it has been opened for writing, an APPC or TCPIP connection can be established to this online system. All commands are processed via the online system. The 'CONNECT' parameter establishes a connection to an online system. The following syntax applies to the 'CONNECT' command: CONNECT [connection name]

The name of the connection must be one of the TCACONTB- entries defined in the tcACCESS generation job. If a connection cannot be established, the first command using the connection terminates with a return code (e.g. '20B00015'). If the basic file is accessed via 'CONNECT', the write status is determined by the definition in the online system. The 'MODE' command must not be submitted here. Example: CONNECT DBDCCICS

4.2.4 COPY CON The 'COPY CON' allows the creation of a virtual disk file. The input data for the file is part of the input stream and follows the COPY CON command. The following syntax applies to the 'COPY CON' command: COPY CON file name

The files are automatically translated from EBCDIC to ASCII and will then be written to the virtual disk. The input data follows the 'COPY CON' command and it is terminated with '$$END'. Then additional parameter may follow. If the input lines are terminated with ‚||’, no CRLF will be generated; the line will be concatenated with the following line. Additional commands may follow. Trailing blanks will be truncated in every line. This function can be deactivated with TRUNCATE OFF command.Example: COPY CON EXPENSIVE.VTB SELECT * FROM VSAM.ARTICLE WHERE ARTICLE.PRICE > 20 $$END

January 2011


4.2.5 DEL The 'DEL' command allows to delete files. The following syntax applies to this command: DEL [file_name | filter]

Example: PART PARTTN MODE U DEL *.* DEL OLDFILE.FTB DEL TABLES/USER/*.FTB

The 'PART' statement defines the partition where files are to be deleted. To write to a virtual disk the write mode must be activated. This accomplished by using the 'MODE U' parameter.

4.2.6 DIR The 'DIR' parameter prints the entries of the directory. The following applies to this command: DIR [-S] [filter]

The directories must be separated with '/'. The '-S' parameter will list the subdirectories. This parameter must to be defined in front of the filter. If no filter is defined, '*.*' is assumed. Example: CD TABLES DIR -S *.FTB DIR TABLES/SYSTEM/*.FTB

4.2.7 FDISK ACTP The 'FDISK ACTP' parameter activates an 'inactive' partition on a virtual disk. The following syntax applies to this command:

FDISK ACTP

January 2011


The partition name to be activated must be defined in a 'PART' statement before FDISK. In order to be able to write on a virtual disk, the write mode must be activated. This is done by using the 'MODE U' parameter. A partition with the 'INACTIVE' status only can be activated. Example: FILE NEWDISK PART ACTPART MODE U FDISK ACTP

This example activates a partition called 'ACTPART' on the virtual disk with the name 'NEWDISK'.

4.2.8 FDISK DELP The 'FDISK DELP' parameter deletes a partition on a virtual disk. The following syntax applies to this command: FDISK DELP

The name of the partition to be deleted must be defined in the 'PART' statement before FDISK. In order to write to a virtual disk the write mode must be activated. This is done by using the 'MODE U' parameter: Only a partition with an 'OK' status can be deleted. Example: FILE NEWDISK PART DELPART MODE U FDISK DELP

This example deletes a partition called 'DELPART' on a virtual disk with the name 'NEWDISK'.

4.2.9 FDISK DIRP The 'FDISK DIRP' parameter prints a partition table of the defined virtual disk. The following syntax applies to this command:

FDISK DIRP

In the following example the partition table of the 'TCAVDI' file is printed. The following syntax applies.

January 2011


FILE TCAVDI FDISK DIRP

The following printout will be produced:

Capacity Occupied storage Number S-Rec E-Rec Defined Name Byte MB Byte MB Perc. Entries Status hex. hex. on at by ---------------------------------------------------------------------------------------------------------------------- DISK0 1048576 1.000 993831 0.948 95% 18 OK 2 41 23.12.1999 10:15:14 USER1DISK1 24117248 23.000 1234293 1.177 5% 784 OK 42 81 16.12.1999 19:25:09 USER1DISK2 1048576 1.000 254288 0.243 24% 14 OK 82 641 09.12.1999 17:49:08 USER2 DISK3 1048576 1.000 21047 0.020 2% 10 OK 642 681 30.11.1999 19:15:11 USER2SYSDSK 1048576 1.000 160685 0.153 15% 79 OK 682 6C1 05.01.2000 10:52:00 BATCH

4.2.10 FDISK FORM The 'FDISK FORM' parameter creates a partition on a virtual disk. The following syntax applies to this command: FDISK FORM SIZE=n

The 'SIZE=' parameter without a further specification defines the size in bytes. The number for the size specification can be up to 16 positions. If 'KB' is defined, a partition in the size of n times 1024 is created, the specification of 'MB' has the effect that MegaBytes are assumed for the creation of the file size. The minimum size for a partition is three times the record length of the basic file. The partition name must be defined in a 'PART' statement. In order to be able to write on a virtual disk, the write mode must be activated. This is done by using the 'MODE U' parameter. Example: FILE NEWDISK PART NEWPART MODE U FDISK FORM SIZE=2MB

This example formats a partition on a virtual disk with a size of 2 MegaBytes. Between the size specification and the optional unit (e.g. KB), you may specify one blank or no blank at all. The 'FORM' command uses the free space of a virtual disk which became available after partitions were deleted (status: 'DELETED') or cleared (status: 'EMPTY'). If the required free space is not available on the basic file, tcACCESS attempts to add the partition at the end of the file. Note: If a partition is enlarged, the space of the partition needs to be explicitly released after deletion, by using

the 'FDISK FREP' command, before the 'FDISK FORM' command can be performed using the same partition name.

4.2.11 FDISK FREP The 'FDISK FREP' parameter releases the storage space of a partition on a virtual disk which has been deleted. Following syntax applies to this command:

January 2011


FDISK FREP

The partition name to be released must be defined in a 'PART' statement. In order to write on a virtual disk the write mode must be activated. This is done by using the 'MODE U' parameter. A partition with the 'DELETED' status only can be released. A released partition can not be restored again with the 'UNDP' command. Example: FILE OLDDISK PART DELPART MODE U FDISK DELP FDISK FREP

This example deletes the partition called 'DELPART' on the virtual disk with the name 'NEWDISK' and releases the storage space which has been occupied by this partition.

4.2.12 FDISK INAP The 'FDISK INAP' parameter inactivates a partition on a virtual disk. The following syntax applies to the command: FDISK INAP

The partition name to be inactivated is defined with a 'PART' statement. In order to be able to write on a virtual disk the write mode must be activated. This is done by using the 'MODE U' parameter. Only a partition with the 'OK' status can be inactivated. Example: FILE NEWDISK PART INAPART MODE U FDISK INAP

This example inactivates the partition called 'INAPART' on the virtual disk 'NEWDISK'.

4.2.13 FDISK UNDP The 'FDISK UNDP' parameter restores a prior deleted partition on a virtual disk. The following syntax applies to this command:

January 2011


FDISK UNDP

The partition name to be restored must be defined in a 'PART' statement. In order to be able to write on a virtual disk the write mode must be activated. This is done by using the 'MODE U' parameter. Only partitions with the 'DELETED' status can be restored. If a create operation for a partition has been performed, or the partition has been explicitly released with the 'FDISK FREP' command, then it is no longer possible to restore it. Example: FILE NEWDISK PART DELPART MODE U FDISK UNDP

This example restores the partition called 'DELPART' on the virtual disk with the name 'NEWDISK'.

4.2.14 FILE The 'FILE' parameter specifies a basic file for processing. This basic file is defined in a DD- or a DLBL-statement. The 'FILE' command together with the 'PART' command defines the basic file or partition which should be processed with the next commands. If the basic file was already processed, the specification of another 'FILE' command has the effect, that the previous basic file is closed and the new basic file will be opened.

4.2.15 MD The MD parameter allows to define a directory in the current directory. The following syntax applies to the 'MD' command:

MD directory name

To write on a virtual disk the write mode must be activated. This is done by using the 'MODE U' parameter. Example: FILE MYDISK PART SYSDSK MODE U MD TABLES MD TABLES/SYSTEM

4.2.16 MODE The 'MODE' parameter allows to define the access mode for a file. The following syntax applies to this command:

January 2011


MODE [ R | U ]

The default value for the 'MODE' command is 'READ' (R). It must be set to 'U' after specifying the basic file and partition, if write operations are to be performed on the basic file. If the 'MODE' command is used, direct accesses will be performed on the specified file. If a connection to the online system is activated via 'CONNECT', the 'MODE' will close this connection and it will be switched to a direct access mode.

4.2.17 PART The 'PART' parameter together with the 'FILE' command determines the basic file or partition which is to be processed with the following commands. The following syntax applies: PART partition name

4.2.18 PWD The ‘PWD’ command defines the password that should be used to establish the connection to the online-system. PWD password

4.2.19 RD The 'RD' parameter card deletes a directory. Only empty directories can be deleted. The following syntax applies: RD directory name

To write to a virtual disk, the write mode must be activated. This is done by using the 'MODE U' parameter. Example: FILE MYDISK PART SYSDSK MODE U RD MYDIR/EMPTY RD MYDIR

4.2.20 RENAME The 'RENAME' parameter allows to rename files or directories. The following syntax applies to this command:

January 2011


RENAME 'old name' 'new name'

To write to a virtual disk, the write mode must be activated. This is done by using the 'MODE U' parameter. Example: MODE U RENAME 'OLD FILE.DOC' 'NEW FILE.DOC' RENAME TABLES/USER1/TESTVIEW.VTB TABLES/PROD/VIEW.VTB

This command allows also to move files and directories within an partition. File names containing blanks must be enclosed in quotes. A '/' is the separation character for directory names.

4.2.21 RESET The 'RESET' parameter resets the 'OPEN' attribute of a file. This function must not be applied, if the 'OPEN' attribute of a file that is already closed has not been reset because of an error.

4.2.22 RESTORE The 'RESTORE' parameter allows to write the data from a defined backup file to a virtual disk. The following syntax applies: RESTORE [-RWD] [Filter]

The backup file must have a corresponding 'BACKUP' DD- or DLBL- statement . The 'RESTORE' command can be processed with parameter. The following parameter are accepted. Parameter must always be defined in front of a filter.

-R Files already existing on the target file are overwritten. -W The tape is rewound after successful completing of the write operation (VSE only). This parameter

must not be used in conjunction with the -D parameter.-D The backup expects a disk file instead of a tape (VSE only). This parameter must not be used in

conjunction with a -W parameter. The 'RESTORE' command accepts filter options to define the files which are to be restored. These filters should be specified in the following way: RESTORE SYSTEM

All files are restored to the 'SYSTEM' subdirectory.

January 2011


RESTORE *.VTB

All files using a name of '*.VTB' filter are restored. If no filter is defined, '*.*' will be assumed. Example: FILE TCAVDI PART SYSDSK MODE U CD TABLES RESTORE

To write on a virtual disk, the write mode must be activated. This is done by using the 'MODE U' parameter.

4.2.23 TYPE The 'TYPE' parameter allows to print files. The following syntax applies: TYPE file name

The files are automatically converted from ASCII to EBCDIC and will then be printed. Example: TYPE EXAMPLE.VTB

4.2.24 TRUNCATE ‘TRUNCATE’ will activate/deactivate the truncation of trailing blanks with a COPY CON command. TRUNCATE ON|OFF

TRUNCATE ON is the standard setting.

4.2.25 USER The 'USER' parameter allows to determine the user identification for the read accesses. For example, files, written to the virtual disk using 'COPY CON', get the defined name as user identification. If the parameter 'USER' does not exist or no name at all has been defined, the identification 'BATCH' will be used by default.

The UserID will also be used when a session to the online system is being established.

January 2011


The following syntax applies: USER user identification

January 2011


4.3 Virtual Disks - Interfaces

Data for virtual disks on the host are stored as RRDS clusters. These VSAM files have a specific format for the administration of the disks, directories and files. This format is not transparent to user written host programs. To ease the access to these files on a virtual disks and to guarantee the data integrity, several interfaces are provided. They provide access to this data from within many host environments. The interfaces allow user written host programs to process the data by using a command set which is similar to the PC DOS command set.

4.3.1 Commands for virtual disks

When the interface is called the following fields are passed:

Field name Data type MeaningTCACMD CHAR(4) Name of the command to be executed.TCAADRPA FULLWORD Address of the TCAGEN program; it must be (Null). TCACTR FULLWORD Counter: This counter has a different meaning depending on the command

to be executed. TCARETC FULLWORD Return code: If an error occurs during the execution of the command, a

value greater (Null) will be returned.TCAHNDL BIN(1) Request ID: This ID allows to send requests to the interface; these requests

may not just only apply to the currently open file. A group of requests get the same request ID.

TCASTFLG BIN(1) reserved TCAFNL HALFWORD Length of the file name passed in 'TCAFNAME' parameterTCAFNAME CHAR(256) File nameTCAFNL1 HALFWORD Length of the new file name passed in the 'TCAFNAM1' parameter. This

field is only needed for the 'RENAME' function.TCAFNAM1 CHAR(256) New file name. This field is only needed for the 'RENAME' function.

CHAR(2) UnusedTCABUFFL FULLWORD Length of the data field. TCABUFF CHAR(MAXFUL

LWORD)Data field: The content of this field depends of the currently used command.

If the name of the virtual disk should be applied in this field, this name consists of the FCT name of the applicable VSAM RRDS file and the 6 digit name of the virtual disk within a CICS environment (e.g. TCAVDI.DISK1).

Note: The Request IDs (field: TCAHNDL) must be specified with the 'INIT' command; the request Ids

remain valid during the entire processing and are released with a 'TERM' command.

For an operational sequence consisting of 'INIT' - execution of several commands - 'TERM' the same ID is always to be used.

Example: Copying a file requires two independent processing operations. One of it is reading the source file; the other is writing into the target file. Two Request Ids are needed. With the first ID the 'INIT' command is submitted and the source file is opened. With a second ID the 'INIT' command is submitted, the target file is opened for writing. Then the copy process is performed, both files are closed by using 'their' IDs and with each of both IDs the term function is called.

January 2011


The following commands are currently supported by the interfaces:

Command DescriptionACTP Activate a partitionASEC Convert a character string from ASCII to EBCDICCLOS Close a file on the virtual diskCREA Create a new file on the virtual diskDELE Delete a file on the virtual diskDELP Delete a partitionDIRN Return name of the next file in the directoryDIRS Start reading the content of the directoryECAS Convert a character string from EBCDIC to ASCIIFORM Format a partitionFREE Return free space of a diskFREP Free space of a deleted partition INAP Inactivate a partition INIT Initialization of the interface (opening files, preparing buffers, etc.)LABL Return name of a disk (label)MKDI Create a directoryOPEN Open a file on the virtual diskRDEA Read data of an open file in ASCII modeREAD Read data of an open fileRELD Get the release number of the interface RENA Rename a file or a directory RESE Reset file attributes SET0..SET2 Move read/write position within a fileTERM Termination of the interface (closing files, releasing resources, etc.)TRON Start a trace in the Batch-environmentTROF Stop a trace in the Batch-environmentTSTU Test the possibility of write accesses on this file UNDP Undelete a partitionWRIT Write data to a fileWRTA Write data in ASCII mode to a file

4.3.1.1 The 'ACTP' Command This command activates the defined partition. The following table shows the content of the fields before and after calling the interface: Field name Content before the call Return valuesCommand ACTP ---Counter --- ---Return code --- Error numberFile name Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

Data --- --- 4.3.1.2 The 'ASEC' Command

This command allows to convert data from ASCII into EBCDIC.

The following table shows the content of the fields before and after calling the interface:

Field name Content before the call Return valuesCommand ASEC ---Counter --- ---Return code --- Error number

January 2011


File name --- ---Data ASCII data EBCDIC data

4.3.1.3 The 'CLOSE' Command

The CLOSE command closes a file which has been opened using an OPEN or CREA command.

The following table shows the content of the fields before an after the interface call:

Field name Content before call Return valuesCommand CLOSE ---Counter --- ---Return code --- Error numberFile name --- ---Data --- ---

4.3.1.4 The 'CREA' Command

The CREATE command defines a new file on a virtual disk or clears an existing file. If the command has been completed successfully, the file is opened for write access.

The following table shows the content of the fields before an after the call of the interface:

Field name Content before call Return valueCommand CREA ---Counter --- ---Return code --- Error numberFile name Name of the file. This name may be specified

together with a directory path. Directory names are separated with '/'.

---

Data Name of the virtual disk (see general description of the field).

---

It is not possible to open more than one file at a time.

4.3.1.5 The 'DELE' Command

The DELETE command deletes an existing file.

The following table shows the content of the fields before an after calling the interface:

Field name Content before the call Return valuesCommand DELE ---Counter --- ---Return code --- Error numberFile name Name of the file. This name may be defined

together with a directory path. Directory names are separated with '/'.

---

Data Name of the virtual disk (see general description of this field).

---

January 2011


4.3.1.6 The 'DELP' command The 'DELP' command deletes a partition on a virtual disk. Field name Content before the call Return valuesCommand DELP ---Counter --- ---Return code --- Error numberFile name Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

Data --- --- 4.3.1.7 The 'DIRN' Command

This command returns the next directory entry after a DIRS or DIRN command has been performed.

The following table shows the content of the fields before and after the call of the interface:

Field name Content before the call Return valuesCommand DIRN ---Counter --- ---Return code --- Error number.File name --- ---Data --- Directory entry (form see DIRS).

4.3.1.8 The 'DIRP' Command This command lists all partitions of a virtual disk. The following table shows the content of the fields before and after calling the interface: Field name Content before the call Return values Command DIRP ---Counter --- Number of bytes used by the data structure:

The quotient of this counter and the number 129 determines the number of returned entries.

Return code --- Error numberFile name Name of the virtual disk; the same disk must

be defined as for the 'INIT' command.---

Data Name of the virtual disk. This buffer must be big enough to return all directory entries within one call.

Partition entry in the form:

• 8 digit partition name• 12 digit size in Bytes• 9 digit size in MB• 1 blank• 12 positions of occupied storage in Bytes• 9 positions of occupied storage in MB• 1 blank• 5 positions of occupied storage in %• 1 blank• 10 digit number of entries• 1 blanks• 10 digit status, see below• 1 blank• 5 digit first record of partition on the file• 2 blanks• 5 digit last record of Partition on the file

January 2011


• 10 digit creation date• 1 blank• 8 digit creation time• 1 blank• 8 digit creator (USERID)• 9 blanks

The buffer must have a sufficient size to return all entries in one call. If this is not the case, the counter shows the number of needed bytes and an error will be returned. The status field may contain one of the following values: 'OK', 'DELETED', 'INACTIVE', 'PENDING', 'EMPTY' and 'READ ERROR'.

4.3.1.9 The 'DIRS' Command

This command starts reading the entries of a directory.


Field name Content before the call Return valuesCommand DIRS ---Counter --- ---Return code --- Error number.File name Name of the directory and specification of a

mask for receiving the directory entries (e.g. DIR1/*.*).

The specification of the selection mask can be made by applying the '*' character for an optional character string and/or '?' for an optional character (e.g. *.FTB, ?abc?.*, etc.).

---

Data Name of the virtual disk. The size of this buffer should be sufficient to return a directory entry (min. 46 bytes).

First directory entry in form of:

• 8 digit file name• 1 blank• 3 digit extension• 1 blank• 9 digit length of file in bytes• 1 blank• 8 digit last access date

(mm-dd-yy)• 1 blank• 8 digit last access time

(hh-mm-ss)

4.3.1.10 The 'ECAS' Command

This command converts data from EBCDIC to ASCII.

The following table shows the content of the fields before an after calling the interface:

Field name Content before the call Return valuesCommand ECAS ---Counter --- ---Return code --- Error numberFile name --- ---Data EBCDIC data ASCII data

January 2011


4.3.1.11 The 'FORM' Command The 'FORM' command defines a new partition on a virtual disk. The following table shows the contents of the fields before and after calling the interface: Field name Content before the call Return valuesCommand FORM ---Counter Partition size in Bytes Size of formatted partition in BytesReturn code --- Error numberFile name Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

Data --- ---

4.3.1.12 The 'FREE' Command

The 'FREE' command returns free storage space information for a disk.


Field name Content before the call Return valuesCommand FREE ---Counter --- Number of bytes still available on a virtual

disk.Return code --- Error number.File name --- ---Data Name of the virtual disk (see general

description of this field).---

4.3.1.13 The 'FREP' Command The 'FREP' command releases the storage space which was occupied by a deleted partition on the virtual disk. It can only be applied for partitions with the 'DELETED' status. After this command has been successfully completed the partition can not be restored. The following table shows the field contents before and after calling the interface: Field name Content before the call Return valueCommand FREP ---Counter --- ---Return code --- Error numberFile name Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

Data --- --- 4.3.1.14 The 'INAP' Command This command sets the status for the defined partition to 'INACTIVE'. The following table shows the field contents before and after calling the interface: Field name Content before the call Return valuesCommand INAP ---Counter --- ---Return code --- Error numberFile name Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

Data --- ---

January 2011


4.3.1.15 The 'INIT' Command

The INIT command initializes the interface.

In a batch, the VSAM file will be opened or a connection using APPC will be established..

The following table shows the contents of the fields before and after calling the interface:

Field name Content before call Return valuesCommand INIT ---Counter --- ---Return code --- Error numberFile name --- ---Data In the data area, the 8 digit USERID will be

supplied. Position 9 controls in a batch environment, how the file should be accessed.

'O' The file is opened for read/writeaccess.

'C' The file will not be opened by the batch job, an APPC- or TCP/IP-connection should be established with a tcACCESS CICS- or tcACCESS Monitor system, which then will perform the data accesses. In this case you must specify the connection id beginning at position 10. (length of 8 bytes)

others:The file is opened in read-only mode.

In a CICS or a tcACCESS Monitor system environment the definition of the VSAM file determines the access mode.

---

4.3.1.16 The 'MKDI' Command

The 'MakeDir' command creates a new directory on the disk.


Field name Content before the call Return valuesCommand MKDI ---Counter --- ---Return code --- Error numberFile name Name of the directory which is to be newly

created.---

Data Name of the virtual disk (see general description for this field).

---

January 2011


4.3.1.17 The 'LABL' Command

The LABEL command delivers the internal name (label) of a disk.

The following table shows the content of the fields before an after the call to the interface:

Field name Content before the call Return valuesCommand LABL ---Counter --- ---Return code --- Error number.File name --- ---Data Name of the virtual disk (see general

description of this field).Disk label of the disk.

4.3.1.18 The 'OPEN' Command

The 'OPEN' command opens an existing file on a virtual disk for read and write access.

The following table shows the contents of the fields before and after the interface has been called:

Field name Content before call Return valuesCommand OPEN ---Counter --- ---Return code --- Error numberFile name Name of the file. This name may be defined

together with a directory path. Directory names are separated with a '/'.

---

Data Name of the virtual disk (see general description of this field).

---

Through the usage of Request-ID's, more than one file can be opened at the same time. It is mandatory to use a single request ID for a sequence: 'INIT' - processing - 'TERM'.

4.3.1.19 The 'OPNR' command

The OPNR command opens an already existing file on the Virtual Disk for read -processing.

The following table shows the contents of the fields before and after the interface has been called:

Fieldname Content before call Return valuesCommand OPNR ---Counter --- ---Return code --- Error numberFile name Name of the file. This name may be defined

together with a directory path. Directory names are separated with a '/'.

---

Data Name of the Virtual Disk (i.e. TCAVDI.SYSDSK).

---

Through the usage of Request-ID's, more than one file can be opened at the same time. It is mandatory to use a single request ID for a sequence: 'INIT' - processing - 'TERM'.

4.3.1.20 The 'RDEA' Command

This RDEA command reads data in ASCII mode from the currently opened file. After the read operation, the read/write position is positioned after the data which has been read. This command reads the defined number of bytes at the maximum. If a character with a value smaller than 32 (ASCII control character) is found in the data, the read process will be terminated. Data occurring until this character represent an ASCII line.

January 2011



Field name Content before call Return valuesCommand RDEA ---Counter Number of bytes to be read. Number of bytes which have been read until

an ASCII control character was found (including the character). If this value is '0', the end of file has been reached.

Return code --- Error numberFile name --- ---Data --- The data which was read. The data is

converted from ASCII into EBCDIC (without the control character).

Through the usage of Request-ID's, more than one file can be opened at the same time. A single Request-ID must be used for a cycle: 'INIT' - processing - 'TERM'.

4.3.1.21 The 'READ' Command

The READ command reads data in the specified length from the currently opened file. After the read operation has been completed the read/write position is positioned after the data, which has been read.


Field name Content before call Return valuesCommand READ ---Counter Number of bytes which are to be read. Number of bytes which have been read. If this

value is smaller than the number of desired data, the end of file has been reached.

Return code --- Error number.File name --- ---Data --- Data which has been read.

Through the usage of Request-ID's more than one file can be opened at the same time. A single Request-ID must be used for a cycle: 'INIT' - processing - 'TERM'. 4.3.1.22 The 'RELD' Command This command returns the current version of the interface. The following table shows the content of the fields before and after calling the interface: Field name Content before the call Return valuesCommand RELD ---Counter --- ---Return code --- ---File name --- ---Data --- Version no. of the interface The data buffer must be allocated in the size of 5 Bytes. 4.3.1.23 The 'RENA' Command This command renames files and directories. The following table shows the content of the field before and after calling the interface:

January 2011


Field name Content before the call Return valuesCommand RENA ---Counter --- ---Return code --- Error codeFile name old file name ---File name1 new file name ---Data Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

The 'RENA' command is used to rename files and directories. Files and directories can also be moved within the same partition. The '/' is the separation character for directories. 4.3.1.24 The 'RESE' Command The 'RESE' command resets the 'OPEN' attribute of a file. This function must not be applied, if the 'OPEN' attribute of a file that is already closed has not been reset because of an error. The following table shows the content of the field before and after calling the interface: Field name Content before the call Return valuesCommand RESE ---Counter --- ---Return-Code --- Error codeFile name Name of file. This name can be defined with

a directory path. Directory names are separated with '/'.

---

Data Name of the virtual disk (e.g. TCAVDI.SYSDSK).

---

4.3.1.25 The 'RMDI' Command

The 'RMDI' command deletes an empty directory.

The following table shows the content of the fields before and after calling the interface:

Field name Content before the call Return valuesCommand RMDI ---Counter --- ---Return code --- Error numberFile name Name of the directory to be deleted. This

directory must not contain any files.---

Data Name of the virtual disk (see general description for this field).

---

4.3.1.26 The 'SET0', 'SET1' and 'SET2' Commands

The SET commands moves the read/write position within an opened file.

• The SET0 command calculates the new position based on the begin of the file.• The SET1 command calculates the new position based on the current location of the read/write position.• The SET2 command calculates the new position based on the end of file.


January 2011


Field name Content before the call Return valuesCommand SETx ---Counter Number of positions the position should

move within the file.Position within the file.

Return code --- Error number.File name --- ---Data --- ---

4.3.1.27 The 'TERM' Command

The TERM command terminates the interface. In a batch or REXX environment the VSAM file is closed. It can be deallocated after this command has been called.


Field name Content before the call Return valuesCommand TERM ---Counter --- ---Return code --- Error numberFile name --- ---Data --- ---

The 'TERM' command terminates the interface for the defined Request ID. This ID is then available again and can be used with another 'INIT' command. It is necessary to define the same ID for the Request ID as defined for the 'INIT' command for the same process. 4.3.1.28 The 'TRON' command

Using the command 'TRON' a trace can be created in a batch environment. This command is not available in an online environment. Tracing for the online environment is controlled by the tcACCESS generation-parameter TRACE=.


Field name Content before the call Return valuesCommand TRON ---Counter --- ---Return code --- ---File name --- ---Data In aVSE-environment, the trace can only be

displayed on the system-console. Field TCABUFFL must have a value of 0.

In an OS/390-environment the trace can either be written to the system-console (TCFABUFFL=0) or into a separate output file (TCABUFFL=8). The name of the DD-statements for this file must be specified in the data field (i.e. TCATRACE). The JCL-statement for the file could look like:

TCATRACE DD SYSOUT=*

---

4.3.1.29 The 'TROFF' command

January 2011


Using the command 'TROFF' you can deactivate the trace in a batch environment. This command is not available in an online environment. Tracing for the online environment is controlled by the tcACCESS generation-parameter TRACE=.

4.3.1.30 The 'TSTU' Command The 'TSTU' command tests, whether it is possible to write on a partition. The following table shows the content of the field before and after calling the interface: Field name Content before the call Return valuesCommand TSTU ---Counter --- ---Return code --- - Update permittedFile name --- ---Data Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

Within CICS the possibility of updating a file depends on the file definitions. The 'Add' and 'Upd' attributes must be defined to write to a file.

4.3.1.31 The 'UNDP' Command This command sets the 'OK' status for a deleted partition'. It is only available for partitions with a 'DELETED' status. The following table shows the content of the field before and after calling the interface: Field name Content before the call Return valuesCommand UNDP ---Counter --- ---Return code --- Error codeFile name Name of the virtual disk (e.g.

TCAVDI.SYSDSK).---

Data --- ---

4.3.1.32 The 'WRIT' Command

The WRITE command allows to write data of the specified length into the current open file. After the write operation, the read/write position is positioned after the data, which has been written.


Field name Content before the call Return valuesCommand WRIT ---Counter Number of bytes which are to be written. Number of bytes which were written. If this

value is smaller than the number of sent data, the virtual disk is full. The calling program should always verify this condition.

Return code --- Error number.File name --- ---Data Data which is to be written. ---

Through the usage of Request-ID's more than one file can be opened at the same time. A single Request-ID must be used for a sequence: 'INIT' - processing - 'TERM'.

January 2011


4.3.1.33 The 'WRTA' Command

This type of WRITE command allows to write data in ASCII format to the currently open file. After the write operation the read/write position is positioned after the data, which has been written. Before writing, the data is converted from EBCDIC to ASCII. The last two bytes of the data are replaced by the ASCII CR/LF sequence (x'0D0A'). Therefore, the calling program should reserve two unused positions after the data.


Field name Content before the call Return valuesCommand WRTA ---Counter Number of bytes to be written. Number of bytes which were written. If this

value is smaller than the number of sent data, the virtual disk is full. The calling program should always verify this condition.

Return code --- Error number.File name --- ---Data Data which is to be written. ---

Through the usage of Request-ID's more than one file can be opened at the same time. A single Request-ID must be used for a sequence: 'INIT' - processing - 'TERM'.

4.3.2 Calling Interfaces

The interfaces to trigger a data transfer from an online-system are implemented in module TCAVDI(.PHASE). Use module TCAVDIL(PHASE) for batch programs. The module of the batch-interface also contains the access via APPC or TCP/IP to the online system.

4.3.2.1 CICS

In a CICS environment an interface is called with the following command:

EXEC CICS LINK PROGRAM('TCAVDI') COMMAREA(VDICOMM) LENGTH(nnn)

Structure of COMMAREA:

Parameter ASSEMBLER Notation COBOL Notation: Command DS CL4 PIC X(4).Reserved DS F PIC 9(8) COMP. Counter DS F PIC 9(8) COMP. Return_code DS F PIC 9(8) COMP. Request-ID DS X PIC X(1). Reserved DS X PIC X(1). File name Length DS H PIC 9(4) COMP. Name DS CL256 PIC X(256). File name 1 Length DS H PIC 9(4) COMP. Name DS CL256 PIC X(256).Reserved DS CL2 PIC X(2). Data Length DS F PIC 9(8) COMP. Buffer DS CLx PIC X(x).

January 2011


The length of the COMMAREA for the LINK command and the buffer length depends on the currently used command.

The 'Reserved' field must contain the value ''.

For a description of the field contents please refer to the description of the commands.

4.3.2.2 MVS or VSE Batch

In a batch environment the interface can be called by any programming language which allows to pass a parameter list in register 1. The name of the interface is 'TCAVDIL'. This program can statically be linked to a user program, as it dynamically loads the interface program to the virtual disk 'TCAVDI' at the execution time.

In register 1 the 'TCAVDIL' program expects a parameter list with the addresses of the following five fields:

• Command• Counter• Return code• File name• Data

The format of the fields is equivalent to the format for a CICS call.

Example in ASSEMBLER:

... COMMAREA DS 0HTCACMD DS CL4 TCAADRPA DS F TCACTR DS F TCARETC DS F TCAHNDL DS X TCASTFLG DS X TCAFNL DS H TCAFNAME DS CL256 TCAFNL1 DS H TCAFNAM1 DS CL256 TCABUFFL DS F TCABUFF DS 0C ... LA R1,COMMAREA L R15,=V(TCAVDIL) BALR R14,R15 ...

January 2011


Example in COBOL:

... 01 COMMAREA. 02 TCACMD PIC X(4). 02 TCAADRPA PIC 9(8) COMP. 02 TCACTR PIC 9(8) COMP. 02 TCARETC PIC 9(8) COMP. 02 TCAHNDL PIC X(1). 02 TCASTFLG PIC X(1). 02 TCAFNL PIC 9(4) COMP. 02 TCAFNAME PIC X(256). 02 TCAFNL1 PIC 9(4) COMP. 02 TCAFNAM1 PIC X(256). 02 TCABUFFL PIC 9(8) COMP. 02 TCABUFF PIC X(nnn). ...

CALL 'TCAVDIL' USING COMMAREA. ...

For a description of the fields please refer to the description of the commands.

For VSE systems, the VSAM file with the virtual disk must be referred to as follows:

// DLBL TCAVDI,'file.name',,VSAM,CAT=catalog

In an MVS environment the following JCL statement is required:

//TCAVDI DD DSN=file.name,DISP=SHR

January 2011


5. Host Initiated Data Transfer

The tcACCESS Listener on the PC allows to execute host initiated operations on an MS-Windows PC. If TCP/IP is used, the Listener waits for messages from the host. If the existing tcACCESS host connection is not TCP/IP based, the 'polling' technology must be used, i.e. the PC will poll the host for a request in defined time intervals.

5.1 Calling the Interface For the access from an online system, the TCAIH2PL(.PHASE) module allows to control the data transfer. The TCAIH2PB(.PHASE) module is provided for batch accesses. The module of the batch interface also contains also the access technology to the online system via APPC.

5.1.1 CICS The interface is called with the following command in a CICS environment:

EXEC CICS LINK PROGRAM('TCAIH2PL') COMMAREA(H2PCOMM) LENGTH(nnn)

Commarea structure: Parameter ASSEMBLER Notation COBOL Notation: Task_name DS CL32 PIC X(32).Function DS CL2 PIC X(2).Return_Code DS CL4 PIC X(4). Return_message DS CL80 PIC X(80). Wait_identifier DS C PIC X(1). Reserved DS C PIC X(1).Wait time DS H PIC 9(4) COMP. Parameter_length DS H PIC 9(4) COMP. Data_length DS H PIC 9(4) COMP. Data Parameter DS 0C PIC X(n). Buffer DS 0C PIC X(n).

The length of the COMMAREA with the 'Link' command and the length of the buffer depends on the currently used command. The 'Reserved' fields must contain the value . For a description of the field contents please refer to the description of the commands.

January 2011


5.1.2 MVS or VSE Batch In a batch environment the interfaces can be called by using any programming language which permits to pass a pointer to the structure of the COMMAREA in register 1. The name of the interface is 'TCAIH2PL'. This program can be linked statically to the user program as it dynamically loads the interface program 'TCAIH2P' during execution time. The 'TCAIH2PL' program expects a pointer to the COMMAREA structure in register 1. Example ASSEMBLER: ... COMMAREA DS 0HREQNAME DS CL32 FUNCTION DS CL2 RETCODE DS CL4 RETMSG DS CL80 WAITFLAG DS C DS C WAITTIME DS H PARLEN DS H DATLEN DS H PARAMS DS 0C DATA DS 0C ... LA R1,COMMAREA L R15,=V(TCAIH2PL) BALR R14,R15 ...

Example COBOL: ... 01 COMMAREA. 02 REQNAME PIC X(32). 02 FUNCTION PIC X(2). 02 RETCODE PIC X(4). 02 RETMSG PIC X(80). 02 WAITFLAG PIC X. 02 RESERVED PIC X. 02 WAITTIME PIC 9(4) COMP. 02 PARLEN PIC 9(4) COMP. 02 DATLEN PIC 9(4) COMP. 02 PARAMS PIC X(nnn). 02 DATA PIC X(nnn). ...

CALL 'TCAIH2PL' USING COMMAREA. ...

January 2011


5.2 Commands for a Host Initiated Data Transfer During the call, the COMMAREA described in chapter "Calling the Interface" will be passed. The commands supported by the interface are listed in the table below. Command Description ST Start a task CA Cancel a task CO Define the connection to be used (Batch only) TR Activate a trace (Batch only) TO Deactivate a trace (Batch only)

5.2.1 The 'ST' Command The 'ST' command allows to start a defined task. If a task is registered by the PC, it can be initiated with the 'ST' command. The meaning of the COMMAREA fields are described below. REQNAME Name of the task registered by the PC.FUNCTION 'ST'WAITFLAG If the host program should wait until the processing of the task has been completed, this

field must contain 'Y'. However, 'N' needs to be specified, if the host program should immediately continue processing.

WAITTIME If the 'WAITFLAG' contains 'Y', this parameter defines the number of seconds which the host program should wait until a timeout occurs. The value defines, that no timeout should occur.

PARLEN Parameter length.DATLEN Length of the Data.PARAMS Parameter to be passed to the PC.DATA Data to be passed to the PC. The data and parameter depend on the type of task. A task defined at the PC can be modified by applying parameter. For example, if the data is dynamic and only known during the runtime of the task and must be transferred to the PC, this data can be passed using the 'DATA' section. The data is written into a TS record during the start of the task and passed to the PC for download.

5.2.2 The 'CA' Command The 'CA' command terminates a task, which ended with a return code. The meaning of the COMMAREA fields are described in the table below. REQNAME Name of the task registered by the PCFUNCTION 'CA'WAITFLAG ---WAITTIME ---PARLEN 24DATLEN ---PARAMS Name of the connection as specified in the connection table (refer to system generation) 8

characters, user ID for this connection (8 characters), password for this connection (8 characters).

DATA ---

January 2011


5.2.3 The 'CO' Command The 'CO' command defines a connection which is needed for processing the task using an online system. This command is available for batch programs only. The meaning of the COMMAREA fields are described in the following table.

REQNAME Name of the task registered by the PCFUNCTION 'CO'WAITFLAG ---WAITTIME ---PARLEN Length of the connection name in 'PARAMS'DATLEN ---PARAMS Name of the connection as defined in the connection table (see system customization).DATA ---

5.2.4 The ‘TR’ Command Using the command 'TRON' a trace can be created in a batch environment. This command is not available in an online environment. Tracing for the online environment is controlled by the tcACCESS generation-parameter TRACE=.

REQNAME Name of the task registered by the PCFUNCTION ‘TR’WAITFLAG --- WAITTIME --- PARLEN In aVSE-environment, the trace can only be displayed on the system-console. Field

TCABUFFL must have a value of 0.

In an OS/390-environment the trace can either be written to the system-console (PARLEN=0) or into a separate output file (PARLEN=8). The name of the DD-statements for this file must be specified in the PARAMS field (i.e. TCATRACE). The JCL-statement for the file could look like:

TCATRACE DD SYSOUT=*DATLEN --- PARAMS Refer to field PARLENDATA ---

5.2.5 The 'TO' command

Using the command 'TROFF' you can deactivate the trace in a batch environment. This command is not available in an online environment. Tracing for the online environment is controlled by the tcACCESS generation-parameter TRACE=.

January 2011


5.2.6 Interface Return codes After returning from the call the 'RETCODE' field of the transfer area contains a value. A text message (field: 'RETMSG') is provided when the PC has transmitted the message. The following table shows the possible return codes: X'20B00000 The PC has sent no RN= keyword. Please contact your local B.O.S. representative.X'20B00001 The PC has sent no PN= keyword. Please contact your local B.O.S. representative.X'20B00002 The PC has sent no LT= keyword. Please contact your local B.O.S. representative.X'20B00003 The PC has sent no IA= keyword. Please contact your local B.O.S. representative.X'20B00004 The PC has sent no IP= keyword. Please contact your local B.O.S. representative.X'20B00005 Error within IP address specification. Internal error. Please contact your local B.O.S.

representative.X'20B00006 The specified function can not be called with this connection type. Internal error. Please contact

your local B.O.S. representative.X'20B00010 During the system customization the input '' has been defined for the H2PCNR parameter.X'20B00011 An attempt was made to register a task. For this task there is no space in the task table. The

number of tasks can be defined with parameter 'H2PCNR' of the system customization.X'20B00012 An invalid CICS release was found. The timeout specification is supported from CICS release ≥

2.3 within VSE or ≥ 3.1 in an MVS environment.X'20B00013 An APPC error has occurred. The connection could not be established. Further information is

provided on the system console.X'20B00014 During the system customization of tcACCESS no APPC connections were defined (Macro

TCACONTB).X'20B00015 The defined connection could not be found in the connection table (Macro TCACONTB).X'20B00016 During the system customization 'N' has been defined for the TCP= parameter.X'20B00017 During system customization the link module for TCP/IP was not found.X'20B00018 The program 'TCAH2PUP' has been called with a parameter which had a syntax error.X'20B00020 A task with this name is already registered.X'20B00021 The specified task was not found.X'20B00022 The PC was asking for a task (polling); this task, however, is not yet activated by the host.X'20B00023 Internal error; Please contact your local B.O.S. representative.X'20B00024 There was no data transferred from the host to the PC. (Informative message)X'20B00030 The PC could not be reached. This error message occurs only for TCP/IP connections.X'20B00031 A host program has started a task but the task is already marked for processing.X'20B00033 The timeout time has been reached, however, the task has not been processed by the PC.X'20B00034 The timeout time has been reached, however, the PC is still processing the task.X'20B00035 Processing of the task was terminated.X'20B1xxxx An error occurred while starting the communication to the PC Listener. The positions marked

with 'xxxx' indicate the TCP/IP error number.

January 2011


5.3 Call of a Host initiated Data Transfer via 'TCAH2PUP' The 'TCAH2PUP' utility program can be used to perform a host initiated data transfer without any programming effort. The 'TCAH2PUP' program can be executed using the following JCL: //RUNH2P JOB ,'RUN THE H2P PGM',CLASS=A,MSGCLASS=S //STEP1 EXEC PGM=TCAH2PUP,REGION=0M //STEPLIB DD DISP=SHR,DSN=tcaccess.v800.loadlib //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * ... Parameter ...

Fig. 7: Example job OS/390 for host initiated Data transfer

// JOB RUNH2P// LIBDEF *,SEARCH=(bos.tcaccess) // EXEC TCAH2PUP,SIZE=AUTO ... Parameter ... /*/&

Fig. 8: Example job VSE for host initiated data transfer

The following commands are accepted by the 'TCAH2PUP' program: CHECK Wait until a certain time is reached.CONNECT Establish connection to the online system.DECR Reduce a variable by a specified value.DEF Declare a variable.EXIT End of processing.GOTO 'GOTO' a defined label.IF Request a condition.INCR Increment a variable by a specified value.ONERROR Error condition handling.PAUSE Wait for a specified time interval.PWD Password for the connection to the online system.PC-PARMS Define parameter for the PC.PC-PARMS ADD Add additional parameter for the PC.PC-TIMEOUT Define timeouts for the PC.PC-WAIT Define wait time for the PC.START Start a task.USER User ID for the connection to the online systemTIMESTAMP Define timestamps in the output report.WAITC Wait until a certain time is reached.WTO Issue messages.

5.3.1 CHECK

January 2011


The 'CHECK' command waits for a defined time period. Different to the 'WAITC' command, processing with the next parameter will immediately continue, if the specified time has passed by. Example: CHECK 04:50:00

5.3.2 CONNECT The 'CONNECT' command establishes a connection to an online system. This connection will be used to process the tasks for the Client PC. Connections to an online system must be defined during the system customization. Details about the definition of these connections can be found in the "tcACCESS Customization " manual, chapter "Batch accesses to the online system". The connections are established by using the "TCACONTB" macro. Example: CONNECT DBDCCICS

5.3.3 DECR The 'DECR' command decrements a value of a variable. No specification uses a decrement value of 1. Examples: DECR COUNTER DECR COUNTER 10

5.3.4 DEF The 'DEF' command declares a numeric variable. An initial value can be defined during the declaration. If nothing is specified, the variables will be initialized to (Zero). Example: DEF COUNTER DEF EIGHT 8

5.3.5 EXIT The 'EXIT' command terminates processing. A defined numeric parameter determines the return code of the job step. If nothing has been specified a previously set return code remains unchanged. Example: EXIT 12

January 2011


5.3.6 GOTO The 'GOTO' command continues processing at another position within the parameter stream. Branching to a specified label can take place. These labels must be indicated by a dot (.) at the first position. When branching to a label, the dot can be omitted. Example: GOTO LABEL ... .LABEL

5.3.7 IF The 'IF' command defines conditions for processing. A condition can be the comparison of a variable and a numeric constant. The following comparison operators are supported:

'='...................equal '>='................greater or equal'<='................less or equal'>'...................greater '<'...................less '<>'................not equal to

After the condition, a label is defined where processing will continue, if the condition results in 'true'. If the condition is 'false', processing will be continued with the next parameter following the 'IF' parameter. Example: IF COUNTER1 < 3 LOOP1 IF I > 67678 LABEL

5.3.8 INCR The 'INCR' command increments the value in a declared variable. It is possible to define the value which should be use to increment the defined variable. If nothing has been specified the increment value will be 1 (one). Example: INCR COUNTER INCR COUNTER 10

5.3.9 ONERROR The 'ONERROR' command evaluates error condition. The following syntax is valid:

January 2011


ONERROR [error code] GOTO | RESUME | EXIT | CCODE [label|code]

ONERROR RESUME The 'RESUME' parameter indicates that the internal error handling for calls to the interface is deactivated. Processing is not terminated with an error message when an error occurs during the call but the error message is returned. It can be interrogated with the 'ONERROR …' command.

ONERROR GOTO This parameter performs a conditional branch. A 'label' must be defined. If the error code is set, processing will be continued with the command following the label. If the interrogated error code is not set, processing is continued with the command following the 'ONERROR' statement.

ONERROR EXIT The 'EXIT' parameter will end processing. If a condition code is defined after the EXIT keyword, it will be changed.

ONERROR CCODE The 'CCODE' parameter sets a condition code; however, processing will not be terminated. This allows the definition of sequences like 'Set condition code, create a message and terminate'.

Note: If the 'error code' is not set, it will be checked for 'not equal to '. This means that an 'ONERROR

EXIT' statement will terminate processing, if the error code is not equal to . Example: ONERROR RESUME ... ONERROR 20B00021 GOTO .TESTCOUNT ONERROR 08150815 GOTO .RET15 ONERROR CCODE 99 ONERROR EXIT 12

5.3.10 PAUSE The 'PAUSE' command defines a wait time. Processing will be delayed until this time has passed. Then processing will be continued with the next parameter. The wait time can be defined in seconds or minutes by using the parameter 'S' (seconds) or 'M' (minutes). Example:

PAUSE 10 SEC PAUSE 5 MIN

5.3.11 PWD

Command ‘PWD’ specifies the password for the connection to the online system. The password is used together with the user ID. Example: PWD passwd

January 2011


5.3.12 PC-PARMS The 'PC-PARMS' command defines parameter which will be passed to the PC during the start of a task. A task defined on a PC may be modified by using these parameter. Example: PC-PARMS 'MI=10000'

5.3.13 PC-PARMS ADD Using command ‘PC-PARMS ADD’ additional parameter can be added to the previous call of ‘PC-PARMS’ . Command ‘PC-PARMS ADD’ can be specified multiple times. Example: PC-PARMS ADD ',PS=5050,ID=AX300,DS=11456'

January 2011


5.3.14 PC-TIMEOUT If the 'PC-WAIT' parameter is used to have the host waiting for the completion of processing by the PC, the timeout can be defined with the 'PC-TIMEOUT' parameter. The time is specified in seconds. If (Null) is defined and the 'PC-WAIT' is used, the host program will wait until the PC has completed the task. PC-TIMEOUT nnn

5.3.15 PC-WAIT The 'PC-WAIT' parameter specifies if the host program should wait until the PC has completed the task. For this, 'YES' must be defined. However, if the host program should immediately continue, this parameter must contain 'NO'. The following syntax is valid: PC-WAIT YES | NO

5.3.16 START The 'START' command activates a task. The parameter specifies the name of the registered task. Example: START ARTICLEDOWNLOAD

5.3.17 TIMESTAMP The 'TIMESTAMP' command defines, that a timestamp of the execution time should be printed in the output report. It is possible to specify either 'ON' or 'OFF' as a parameter. Examples: TIMESTAMP ON TIMESTAMP OFF

5.3.18 USER Command ‘USER’ specifies the user ID for the connection to the online system. The user ID will be used together with the password.

January 2011


Example: USER userid

5.3.19 WAITC The 'WAITC' command waits until the defined time has been reached. Different to the 'CHECK' command it will wait for this time until the next day, when the specified time has already passed by on this day. Example: WAITC 04:50:00

5.3.20 WTO The 'WTO' command writes a defined message on the system console or into the job log. It is possible to specify an optional message. The '&MSG' variable issues the message which was the last one sent by the PC. Example: WTO 'Processing is continued.' WTO &MSG

January 2011


6. User specific Host Server

A tcACCESS Host Server Module consists of an independent program which implements the logic and access mechanisms required for the supported data source.

Although there are tcACCESS Server Modules provided for most of the data sources, the need for individual Server Modules may arise. This may be necessary, when a specific data format has been developed which deviates from the IBM host conventions.

Another reason for a user specific server may be the existence of complex data structures or interdependences - even when they are saved in one data source - which could be processed by applying one of the basic access modules.

The Communication Manager analyzes the user requests and passes them in a defined interface to the tcACCESS Server Module COMMAREA. The Server Module performs the respective operations, occupies the needed fields of the COMMAREA and returns control to the Communication Manager. This in return sends the result to the client.

The Server Module can access all available resources except terminal I/O.

The name of a user specific Host Server must consist of the prefix 'TCA' + 4 digit optional name + suffix 'Q' (e.g. TCASRV1Q).

January 2011


7. Index

3270-application data SQL-Engine.......................95ABS().....................................................................31ACOS()..................................................................31ADABAS...............................................................84ADABAS ISN.......................................................85AND......................................................................24APPEND=.............................................................17ASIN()...................................................................31ATAN().................................................................32ATAN2()...............................................................32ATANH()..............................................................32AVG()....................................................................57BETWEEN......................................................24, 25BIN().....................................................................32CALL.....................................................................18Catalog functions.................................................116CEIL()....................................................................32CHAR()...........................................................33, 55COALESCE()........................................................33COMMIT...............................................................19CONCAT()............................................................34Constants...............................................................29COS().....................................................................34COSH()..................................................................34COUNT()...............................................................57CURRENT_TIMESTAMP().................................34DATACOM/DB....................................................83DATE()..................................................................34DAYOFMONTH()................................................35DAYOFWEEK()...................................................35DAYOFYEAR()....................................................36DAYS()..................................................................36DB2 UDB-access.................................................101DBID=...................................................................83DBNR=..................................................................84DECIMAL()..........................................................36DECODE()............................................................37DEGREES()..........................................................37DELETE................................................................19DELETE_SCRIPT=..............................................96DELTSQ=..............................................................66DIGITS()...............................................................38DISTINCT.......................................................57, 58DL/I APPEND.......................................................77DL/I Segments.......................................................69EDN.......................................................................87ELEMENTLIST=..................................................83EXP().....................................................................38Expressions ...........................................................29Field Exit program.................................................64Field Exit Program...............................................105FIELD=..................................................................63FLOAT()................................................................38FLOOR()...............................................................39FNR=...............................................................84, 85FROM....................................................................23FROMTIME=........................................................15FTB file...........................................................12, 62

GROUP BY...........................................................27HAVING...............................................................27HDAM_CHECK...................................................78HEX()....................................................................39HEXCHR()............................................................39Host file.................................................................17HOSTFILE=..........................................................62HOSTPARM=.......................................................82HOUR().................................................................39IDMS.....................................................................87IFNULL()..............................................................40IN...........................................................................26INSERT.................................................................20INSERT_INITIALIZE=........................................66INSERT_SCRIPT=...............................................96INSERT()..............................................................40INT()......................................................................40JULIAN_DAY()....................................................41KEYCHECK=.......................................................16LAST_DAY()........................................................41LCASE()................................................................41LEFT()...................................................................41LENGTH()............................................................42LIKE......................................................................25Literals...................................................................29LN().......................................................................42LOADMODULE=...............................................107LOCATE().............................................................43LOG10()................................................................42LTRIM()................................................................43MAX()...................................................................57MAXIO=...............................................................16MAXROW=..........................................................16MICROSECOND()...............................................44MIDNIGHT_SECONDS()....................................44MIN().....................................................................58MINUTE().............................................................43MOD()...................................................................44MONTH()..............................................................44MVS PS/PO Files..................................................79MVS VSAM Files.................................................80NEXT_DAY().......................................................45NOCOMMIT.........................................................20NOGROUPBY=....................................................16NOORDERBY=....................................................16NULL..............................................................26, 30NULLIF()..............................................................45ODBC..................................................................116Operators.........................................................24, 29ORACLE access....................................................98ORDER BY...........................................................28Outer Joins.............................................................26OUTPUT_FILE=................................15, 16, 59, 60OUTPUT_FORMAT=..........................................17OUTPUT_NULL_INDICATOR=........................17PARMLIST=...............................................107, 113PI().........................................................................46POSSTR()..............................................................46

January 2011


POWER()..............................................................46Precompile parameter............................................60Precompiled SQL-statements................................59PREFETCH=...................................................84, 90PROJECT=............................................................95QUARTER()..........................................................46RADIANS()...........................................................47RAND().................................................................47READ_UPDATE_SCRIPT=.................................96RECEXIT=............................................................66REPEAT().............................................................47REPLACE()...........................................................47RIGHT()................................................................48ROLLBACK..........................................................20ROLLBACK_SCRIPT=........................................97ROUND_TIMESTAMP().....................................48ROUND()..............................................................48RTRIM()................................................................49Rules for index controlled access........................118Search condition....................................................24SECOND()............................................................50Security................................................................115SELECT................................................................22SELECT DISTINCT.............................................22Sequence of table accesses..................................118SET_SQLID=........................................................18SIGN()...................................................................50SIN()......................................................................50SINH()...................................................................50SPACE()................................................................51SQL............................................................................

Comment..........................................................15Option..............................................................15 Syntax.............................................................15

SQL Engine.......................................................7, 10SQL Functions.......................................................31SQL-Statement-Exit.............................................122SQRT()..................................................................51SSA=......................................................................69STARTKEY=................................68, 69, 83, 88, 96Stored Procedure...................................................19

COMMAREA................................................109 Definition......................................................107 Example........................................................110

STP_COMPAT=...................................................18STP-file................................................................107STR_DELIM=.......................................................18STR().....................................................................51STRIP().................................................................51STRUCTURE=......................................................66

SUBDIR=..............................................................62SUBSTR().............................................................52SUM()....................................................................58SYNCPOINT_SCRIPT=.......................................96SYSCOL.FTB.....................................................116SYSDSK................................................................62SYSPCOL.FTB...................................................116SYSPROC.FTB...................................................116SYSTAB.FTB.....................................................116System Entries.......................................................13Table definition.....................................................62TABLES................................................................62TAN()....................................................................52TANH().................................................................52TCAU1................................................................105TCAVDSK............................................................62TD-Queues.............................................................68TIME()...................................................................54TIMEOUT=...........................................................95TIMESTAMP().....................................................54TRANSLATE().....................................................53TRUNCATE_TIMESTAMP()..............................53TRUNCATE().......................................................53TS Queues.....................................................66, 120UNION..................................................................28UPDATE...............................................................28UPPER()................................................................55USER()..................................................................55Variables in host file..............................................62Variables in Host file.............................................17VDISK_BIN=........................................................94VDISK_FIXLEN=................................................94View Definition...................................................104Virtual disk............................................................92Virtual disk................................................................

Assignment......................................................14 Initialization....................................................14 System entries.................................................14 User entries.....................................................14

VSAM Files...........................................................68VSAM RRDS/RRNN............................................83VSAM/RRDS RRN.........................................69, 80VSE Batch VSAM Files........................................80VSE SAM files......................................................82VTB file...........................................................12, 62WEEK_ISO()........................................................56WEEK().................................................................56WHERE.................................................................23Year().....................................................................56

January 2011

tcaccess - host server module - treehouse software, inc. · tcaccess version 8.0.0 host server 1....

Documents