ross iaf connect user guide 73

Internet Application Framework

ConnectUser GuideVersion 7.3CON-UG-73

THE INFORMATION CONTAINED IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT NOTICE. ROSS SYSTEMS, INC. MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE DOCUMENTATION, FUNCTION, AND PERFORMANCE OF THESE PROGRAMS. ROSS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

ROSS SYSTEMS, INC. SHALL NOT BE LIABLE FOR ANY ERRORS CONTAINED

HEREIN OR FOR INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL. LIABILITY FOR DIRECT DAMAGES IS LIMITED TO THE COST OF THE MATERIALS.

This document contains proprietary information which is protected by copyright. No part of this document may be reproduced in any manner or translated into another program language without the prior written consent of Ross Systems, Inc.

(c) Copyright 2005 Ross Systems, Inc. All Rights Reserved.

Ross Systems, Renaissance, Renaissance CS, and Strategic Application Modeler (SAM) and are registered trademarks of Ross Systems, Inc.

GEMBASE, iRenaissance ERP, iRenaissance APS, iRenaissance SCM, iRenaissance CRM, iRenaissance Localization and Customer Portal are trademarks of Ross Systems, Inc.

Other trademarks mentioned herein are the property of their respective owners.

Ross Systems, Inc.Corporate HeadquartersTwo Concourse Parkway, Suite 800Atlanta, Georgia 30328(770) 351-9600

ContentsConnect 7.3 User Guide

Overview.............................................................................................................. 1-1Introduction................................................................................................. 1-1Chapter contents ......................................................................................... 1-2Connect technology .................................................................................... 1-2Web applications ......................................................................................... 1-2Framework classes ...................................................................................... 1-3IAF enterprise server .................................................................................. 1-3

Web Applications................................................................................................. 1-4Introduction................................................................................................. 1-4Sample usermap.config file ........................................................................ 1-4Sample web.config file ............................................................................... 1-5xpo.aspx parameters.................................................................................... 1-6URL example .............................................................................................. 1-7xmltable.aspx Web application parameters................................................. 1-8URL example .............................................................................................. 1-9

Connect Programming ....................................................................................... 1-10Introduction............................................................................................... 1-10Web services ............................................................................................. 1-10Connect Classes ........................................................................................ 1-10Error Handling .......................................................................................... 1-10Switching Usernames for a Connection.................................................... 1-11ADO.NET Dataset XML Format.............................................................. 1-12Passing Tables as Stored procedure parameters........................................ 1-14Related documents .................................................................................... 1-15

IAF Enterprise Server ........................................................................................ 1-16Introduction............................................................................................... 1-16Additional requirements ........................................................................... 1-16Related documents .................................................................................... 1-16gem_xmlpack library ................................................................................ 1-17SEND_XML_TABLE...................................................................................................... 1-18Flag value samples.................................................................................... 1-20DML example 1 ........................................................................................ 1-20DML example 2 ........................................................................................ 1-21RECEIVE_XML_TABLES...................................................................... 1-21DML example ........................................................................................... 1-21New DML Commands.............................................................................. 1-22Send XML Table DML Sample 1............................................................. 1-22Send XML Table DML Sample 2............................................................. 1-22Receive XML Tables DML Sample ......................................................... 1-22

Sample Programs ............................................................................................... 1-23 iiiCON 7.3 UG 12/05

Introduction............................................................................................... 1-23procs.gem.................................................................................................. 1-23 ivCON 7.3 UG 12/05

Connect 7.3 User GuideOverview

Introduction The Connect product provides connectivity to IAF stored procedures from a Microsoft .NET platform. This new technology supports an XML interface to IAF stored procedures as well as a direct API similar to the GDO COM-based product. A complete set of classes is provided to support XML-RPC (SOAP)-style calling of IAF stored procedures through a generic HTTP/IIS Web application. Connect is state-of-the-art technology that utilizes the latest advances from Microsoft to provide World Wide Web connectivity to IAF via the Microsoft .NET Framework.

Continued on next page

XML

IIS Web Server

Web Applications

Connect .NET

Framework Classes

IAF Enterprise Server

Business Logic

Database Interface

HTTP

TCP/IP1-1CON 7.3 UG 12/05

Overview, Continued

Chapter contents This chapter introduces the various components of Connect 7.3 and related technologies. This information is then expanded in more detail in the following topics of the Guide.

Connect 7.3 uses IIS as the Web Server component to provide Web application support. Some Web applications are provided. .NET Framework classes (types) are provided for programming with Connect.

Connect technology

The Connect technology is a set of .NET Framework classes which, at the highest levels, provide XML-RPC style access to IAF DML stored procedures, and, at the lowest levels, communicate directly with the IAF Server using the TCP/IP protocol.

The Microsoft Internet Information Server (IIS) Web server, along with generic and custom Web applications, is used to provide the middle-tier framework for sending XML/XSL-formatted data to and from IAF stored procedures and the World Wide Web.

The low-level .NET Framework classes utilize a TCP/IP socket connection to implement the messaging layers for communicating with the IAF Enterprise Server. These classes include IAF Session-layer and utility classes.

Web applications Connect 7.3 Web applications run in IIS and provide middle-tier services. These applications receive XML formatted requests from the client. The requests are processed using the Connect .NET Framework classes to communicate with the IAF Server to execute IAF Stored Procedure DML. The stored procedures perform business logic and return responses via the middle tier to the client.

Two Web applications are provided with Connect 7.3: XPO and XMLTABLE. XPO is a generic Stored Procedure runner. XMLTABLE retrieves a table from the IAF Server by running a companion stored procedure.

Connect programmers can use XPO and XMLTABLE or they can create their own Web applications using the Connect .NET Framework classes.

Continued on next page1-2 Connect 7.3 User GuideCON 7.3 UG 12/05

Overview, Continued

Framework classes

The Connect .NET Framework API is delivered in the following assemblies:Connect.ComponentsConnect.ServicesGembase.SessionGembase.UtilThese classes are designed to allow Connect programmers to create applications that communicate directly with the IAF Enterprise Server. As such, classes are provided for formatting and parsing XML requests and responses, and for messaging with IAF via the IAF Session layer and TCP/IP.

The classes are discussed in this user guide and detailed documentation is available on-line by going to the CodeCommentReport sub-folder installed during the Connect 7.3 installation.

IAF enterprise server

An IAF Enterprise Server is required for use with Connect 7.3. Connect applications communicate with the Enterprise server to process client requests.

An additional IAF library, gem_xmlpack, is required for use by the IAF server and is included with the Connect distribution. This library incorporates the Expat XML 1.0 non-validating parser from http://www.jclark.com/xml and provides support for sending and receiving IAF tables in XML format through the SEND_XML_TABLE and RECEIVE_XML_TABLES external procedures.Connect 7.3 User Guide 1-3CON 7.3 UG 12/05

Web Applications

Introduction The two standard Web applications included with Connect provide access to IAF stored procedures through standard HTTP GET and POST requests.

xpo.aspx is designed as a generic IAF stored procedure runner. xmltable.aspx is a customized version of xpo.aspx that retrieves IAF tables

as XML.

These two applications obtain their IAF connection information from a file named usermap.config, which must be located in the directory containing the *.aspx files.

Note: For Connect 2.0 Users, the format of the usermap.config file is the same as the usermap.properties file used with Connect 2.0. The name has been changed to usermap.config because IIS will not deliver config files to the browser.

Sample usermap.config file

The usermap.config file is the place where the username, password, and server application connection information are stored. Information for multiple connections may be stored in this configuration file.

Note: Modifications to this file do not require IIS to be stopped and restarted.

The following example specifies two possible server connections.

DEFAULT.hostname=localhostDEFAULT.port=6065DEFAULT.username=joeDEFAULT.password=secretDEFAULT.application=XMLDEMOFIN.hostname=pcnameFIN.port=6065FIN.username=xmlFIN.password=dataFIN.application=b2bserver


Web Applications, Continued

Sample web.config file

An alternate way of configuring the two Connect web applications is provided by the IafConfig.xml file. This is the standard way of configuring IIS ASP.NET applications. TheIafConfig.xml file is an XML format file and resides in the IIS virtual folder for the Connect application (the folder containing the *.aspx files). Connection configuration parameters should be added between a pair of tags. The default IAF installation produces syntax such as this:

- - - ATLWXPC.rossinc.com 6065 iaf iaf XMLDEMO Note: It is recommended that you use either usermap.config or web.config you do not have to use both.

Continued on next pageConnect 7.3 User Guide 1-5CON 7.3 UG 12/05


xpo.aspx parameters

Use the parameters in the table below to enable the xpo.aspx stored procedure runner.


Parameter DescriptionDb=FIN The IAF connection specified in the resource

bundle currently loaded from the usermap.config file. If not specified, then DEFAULT is used.

Debug=hostname For using the IAF DML stored procedure debugger (hardcoded to port 5117).

Trace={0..5} Turns on built-in runtime debugging and can be turned on using the usermap.config file if you wish to log to a file.

Pn=stored procedure name

IAF DML stored procedure name.

P1 ... Pn The stored procedure parameters.enc=encoding name Specifies the encoding to be used on the

response sent back to the user. For example, if used with an encoding name of iso8859-1, the response document includes the following XML header string:

This parameter overrides the encoding specified in the usermap.config file.

secUN=username Specifies the username used for the IAF connection named in the db parameter. Overrides the username specified in the usermap.config file.

secPW=password Specifies the password used for the IAF connection named in the db parameter. Overrides the password specified in the usermap.config file.1-6 Connect 7.3 User GuideCON 7.3 UG 12/05


URL example The following URL places an HTTP GET request to the xpo.aspx Web application, telling it to run the IAF stored procedure XMLGETTABLE with a table name parameter of VT_XML_DEMO. In this case, it would return the IAF table VT_XML_DEMO as an XML stream. (See Sample Programs on page 1-23 for information on setting up the XMLGETTABLE stored procedure.)http://localhost/connect/xpo.aspx?pn=XMLGETTABLE&p1=VT_XML_DEMO

Continued on next pageConnect 7.3 User Guide 1-7CON 7.3 UG 12/05


xmltable.aspx Web application parameters

Use the table below to set the parameters to retrieve IAF tables as XML.


Parameter DescriptionDb=FIN The IAF connection specified in the resource

bundle currently loaded from the usermap.config file. If not specified, then DEFAULT is used.

Trace={0..5} Turns on built-in runtime debugging and can be turned on using the usermap.config file if you wish to log to a file.

tablename=table name The name of the IAF table to retrieve.enc=encoding name Specifies the encoding to be used on the

response sent back to the user. For example, if used with an encoding name of iso8859-1, the response document includes the following XML header string:

This parameter overrides the encoding specified in the usermap.config file.

secUN=username Specifies the username used for the IAF connection named in the db parameter. Overrides the username specified in the usermap.config file.

secPW=password Specifies the password used for the IAF connection named in the db parameter. Overrides the password specified in the usermap.config file.1-8 Connect 7.3 User GuideCON 7.3 UG 12/05


URL example The following URL places a HTTP GET request to the Web application xmltable.aspx, requesting that IAF metadata as well as table data be returned for the IC_LOT_STATUS table in the form of an XML document. (See Sample Programs on page 1-23 for information on setting up the XMLGETTABLE stored procedure.)http://localhost/connect/xmltable.aspx?tablename=IC_LOT_STATUSConnect 7.3 User Guide 1-9CON 7.3 UG 12/05

Connect Programming

Introduction The Connect .NET Framework assemblies provide the basic support classes for calling IAF stored procedures from any .NET Framework language. These classes are provided to ease the migration of Connect 2.0 applications to Connect 7.3

Web services ConnectService is provided with Connect 7.3 as an example of how to expose some of the functionality of Connect as a Web Service. Several Web Methods are provided for executing stored procedures and sending and receiving data tables. The service runs in IIS and is written using C# and the Connect .NET classes to communicate with the IAF Enterprise Server.

Rather than expose Connect functionality as a Web service, users might want to use Connect 7.3 to publish their business logic (stored procedures) as Web services.

Connect Classes Several classes exist for advanced programmers wishing to create their own middle-tier components, for use in web applications or web services, as alternatives to using the standard XPO Web Application or the ConnectService Web Service.

The three primary classes are GemStandardServer, GemXmlServer and, with Release 7.3, GemProcServer. Please see the Samples folder created as part of the Connect installation for examples of how to use these classes.

* GemProcServer new with release 7.3, is a new Class similar to GemStandardServer but provides extended error handling.

Error Handling The Connect 7.3 release enhances the Connect client/server infrastructure to better handle errors.

In general, when encountering an error running a stored procedure, Connect will try to return the following information: error message, form name, DML stack trace, and C# stack trace.

If the stored procedure needs compiling first, and a compile error is encountered, the following information is returned: compile error message, DML filename, line number, and C# stack.

Here are some example error situations:

Procedure not found in application

The error information now includes the name of the missing procedure and the C# stack.

Bad column headings sent to a table1-10 Connect 7.3 User GuideCON 7.3 UG 12/05

The error information now includes the table name, row number, field name, C# stack trace and the DML stack trace.

Sending bad data to a tableInformation now includes table name, row number, field name, field value, DML stack trace and the C# stack trace.

Sending bad xml to the serverThe returned information now includes the line number of the error in the xml document.

Switching Usernames for a Connection

With versions of Connect prior to Connect 7.3, user identity (%USERNAME) is established when connecting to the server, and remains for the duration of the connection. Starting with Connect 7.3, Connect allows a gem_server to execute several stored procedures under different usernames, for a given server connection. This feature is designed for performance and is available using the new class, GemProcServer. As the username switching occurs, authentication takes place via the Broker and facility security is enforced.

The GemProcServer class has an additional Execute method for this functionality:Execute(username, password, procedure, parameters);This method enables the caller to set a new username/password before executing the stored procedure. The username/password remains in effect until a new one is set or until the connection is closed. (If that call is followed with a regular Execute(proc, params) call, that too will use the new username/password)

The gem_server uses the Broker to authenticate the username/password with the operating system and the Broker will also check the Applications ACCESS_SCOPE, ALLOW_USERS and DISALLOW_USERS resources from the resource file.

For performance reasons however, gem_server also keeps a cache of valid username/passwords so that it does not need to go to the broker every time. Once the cache has been primed, theres essentially no cost for the authentication. The cache is purged when the client/gem_server connection is closed.

When a new user is set for an existing connection, the following processing takes place:

all virtual tables are deleted (just like at the end of a connection) cached transactions are committed, any outstanding transactions are

rolled-back (just like at the end of a connection) Connect 7.3 User Guide 1-11CON 7.3 UG 12/05

The new username is set into %USERNAME. Note that this is the application username; the operating system uid/gid is not changed (just like it is not changed at the end of a connection) and the database username/password is not changed thats established when the database is invoked, typically in the resource file for the application.

facility tree privileges are reset (just like at the end of a connection) this is to enforce facility security for the new username

ADO.NET Dataset XML Format

With Connect 7.3, Connect now supports two XML formats: the original IAF Connect format and also Microsofts ADO.NET DataSet format.

The following shows two example tables in IAF XML format:

username1 dataOne0 dataTwo0 username2 dataOne1 dataTwo1 vtusername1 vtdata1value1 vtdata2value1

Note that in IAF XML format, with just one table, you don't need the tags. For multiple tables, you do need these tags because the parser insists on a single "root" node.

Same two tables in MS XML format:


Note that in MS ADO XML format, we DO support a DataSetName of "tables" and a table name of "table". The following case is detected as being MS ADO XML format because the tag has no "name=tablename" attribute.1-12 Connect 7.3 User GuideCON 7.3 UG 12/05


When sending XML to gem_server, you can use either format gem_server will automatically detect the format during parsing and act appropriately.

Heres an example client program that sends a DataSet to a server:public void GemProcPutTest2(){

Console.WriteLine("GemProcPutTest2...");GemProcServer gem = null;try {

gem = new GemProcServer();gem.Open(host, port, application, username, password);// Create the DataSet to send.DataSet ds = new DataSet();string tableName = "XML_DEMO";ds.Tables.Add(tableName);System.Type stringType = Type.GetType("System.String");ds.Tables[tableName].Columns.Add("USERNAME", stringType);ds.Tables[tableName].Columns.Add("DATA1", stringType);ds.Tables[tableName].Columns.Add("DATA2", stringType);for (int row = 1; row

PROCEDURE_FORM ADOGETTABLE (#TABLENAME, #STATUS)

EXTERNAL "XMLPACK" SEND_XML_TABLE ( DSTRING.D, LONG.V )EXTERNAL "XMLPACK" SEND_TEXT ( DSTRING.D )CALL SEND_TEXT( "" )CALL SEND_XML_TABLE( #TABLENAME, 16777216 )CALL SEND_TEXT( "" )#STATUS = %STATUS

END_FORMEach call to SEND_XML_TABLE will generate XML for just that table. The sample uses one SEND_XML_TABLE call, but several could be used if there are several tables to be sent to the client. The SEND_XML_TABLE calls must be surrounded by SEND_TEXT calls to send the start and end tags for the DataSet name. The actual name used is not too important, but the tags are needed so that the XML sent to the client has a single root node. Without this single root node, the client would not be able to parse the XML.

The following client program receives a table from the server as a DataSet:public void GemProcGetTest2(){

GemProcServer gem = null;try {

gem = new GemProcServer();gem.Open(host, port, application, username, password);ArrayList argList = new ArrayList();argList.Add("XML_DEMO");argList.Add("0");int status = gem.Execute("ADOGETTABLE", argList);

string data = gem.GetStreamOutputData();StringReader reader = new StringReader(data);DataSet ds = new DataSet();ds.ReadXml(reader);Console.WriteLine("DS is:\n{0}", ds.GetXml());

}catch(GemException e){

Console.WriteLine("Failed: {0}", e.ToString());}finally {

if (gem != null)gem.Close();

}}

Passing Tables as Stored procedure parameters

Starting with Connect 7.3, tables can be passed between client and server as stored procedure parameters. This is an alternative to the currently supported mechanisms that dont require that tables are specified as stored procedure parameters.

You might want to pass tables as stored procedure parameters if, for example, you want them to become part of the definition or specification of the interface or contract between client and server. Mentioning tables on the procedure calls helps to keep the client side and server side code in sync.1-14 Connect 7.3 User GuideCON 7.3 UG 12/05

To pass a table to a stored procedure, on the client side, create a string containing the XML for the table. The XML must be in Microsoft ADO.NET XML format. This can be done by taking a Dataset object and serializing it to XML. Pass the string as a parameter to a stored procedure. On the server side, in the stored procedure, use the new IMPORT /XML statement to import the table from the XML string parameter.

To pass a table in the other direction, from a stored procedure to a client side C# program, use the new EXPORT/XML statement in the stored procedure to convert a table to an XML string. Pass the string back to the client via the stored procedure parameter (which will need to be defined as /PASS=REFERENCE). In the C# client, read the XML into a Dataset. The following is an example C# client to receive the XML string from the stored procedure.

public void GemProcGetUsingExportXmlTest(){

GemProcServer gem = null;try {

gem = new GemProcServer();gem.Open(host, port, application, username, password);ArrayList argList = new ArrayList();string tableName = "members";string xml = "";argList.Add(tableName);argList.Add(xml);int status = gem.Execute("EXPORT_XML_TABLE", argList);xml = (string)argList[1];DataSet ds = new DataSet();StringReader reader = new StringReader(xml);ds.ReadXml(reader);

}catch(GemException e){

Console.WriteLine("Failed: {0}", e.ToString());}finally {

if (gem != null)gem.Close();

}}

Related documents

More detailed documentation of the Connect classes can be found on-line by viewing the documentation installed under the Connect installation directory.Connect 7.3 User Guide 1-15CON 7.3 UG 12/05

IAF Enterprise Server

Introduction An IAF client-server DML-based stored procedure environment is required to support the Connect technology. This provides the infrastructure and implements the OP_CLN_RPC_BYTE_STREAM message (new bulk transfer message utilized by the Connect classes). The IAF broker/server may run on any supported platform (Windows, VMS, UNIX).

Additional requirements

An additional IAF library (gem_xmlpack) is required and is included in the Connect distribution. This library incorporates the Expat XML 1.0 non-validating parser from http://www.jclark.com/xml and provides support for sending and receiving IAF tables in XML format through the SEND_XML_TABLE and RECEIVE_XML_TABLES external procedures.

Related documents

The following documents provide additional useful information.

IAF User Guide Guide to Using IAF Studio Debugger Guide to Installing IAF Enterprise Server for Windows Guide to Installing IAF on UNIX Guide to InstallingIAF on OpenVMS


IAF Enterprise Server, Continued

gem_xmlpack library

The gem_xmlpack library for your specific platform can be found in the xmlpack sub-directory under the Connect installation directory. The following table outlines the required setup for using the external procedures.


Platform SetupAIX Copy the file gem_xmlpack.so to your AIX server. If you

use FTP to do this, ensure you copy with the binary option. Ensure your IAF resource file (.res) has the following entry:set_env=XMLPACK=/path/to/gem_xmlpack.so

Tru64-formerly DEC UNIX

Copy the file gem_xmlpack.so to your DEC server. If you use FTP to do this, ensure you copy with the binary option. Ensure your IAF resource file (.res) has the following entry:set env=XMLPACK=/path/to/gem smlpack.so

HP-UX Copy the file gem_xmlpack.sl to your HP server. If you use FTP to do this, ensure you copy with the binary option. Ensure your IAF resource file (.res) has the following entry:set_env=XMLPACK=/path/to/gem_xmlpack.sl

Windows (Intel)

Ensure your IAF server resource file (.res) has the following entry (where CONNECT_HOME is the installation directory):set_env=XMLPACK=\xmlpack\winNT\gem_xmlpack.dll

Solaris Copy the file gem_xmlpack.so to your Solaris server. If you use FTP to do this, ensure you copy with the binary option. Ensure your IAF resource file (.res) has the following entry.set_env=XMLPACK=/path/to/gem_xmlpack.so

VMS Copy the file gem_xmlpack.bck to your VMS server. If you use FTP to do this, ensure you copy with the binary option. Unpack this file with the commands:$ set file/attr=(lrl:32256) gem_xmlpack.bck$ backup gem_xmlpack.bck /save []

Ensure your IAF resource file (.res) has the following entry.set_env=XMLPACK=somedirectory:gem_xmlpack.exeConnect 7.3 User Guide 1-17CON 7.3 UG 12/05


SEND_XML_TABLE

The SEND_XML_TABLE external procedure packages an IAF table as an XML stream and sends the XML to the client. It accepts the following parameters:SEND_XML_TABLE(tablename, flags)

The following table lists the possible flag values, which may be added together to produce the desired metadata and data combinations.


Parameter Descriptiontablename Identifies the IAF table to send the client as an

XML document.flags Specifies what combination of data or metadata to

include.

Hex Dec XML Tags0x00000000 0 TABLE_TAGS_ONLY0x00000001 1 TABLE_DATA0x00000002 2 TABLE_NAME0x00000004 4 TABLE_DESCRIPTION0x00000008 8 TABLE_VIRTUAL0x00000010 16 FIELD_NAME0x00000020 32 FIELD_DATA_TYPE0x00000040 64 FIELD_INPUT_MASK0x00000080 128 FIELD_OUTPUT_MASK0x00000100 256 FIELD_MISSING0x00000200 512 FIELD_INITIAL_VALUE0x00000400 1024 FIELD_COMPUTED_SOURCE1-18 Connect 7.3 User GuideCON 7.3 UG 12/05


SEND_XML_TABLE (continued)


Hex Dec XML Tags0x00000800 2048 FIELD_VALID_VALUES0x00001000 4096 FIELD_DESCRIPTION0x00002000 8192 FIELD_NUMBER0x00004000 16384 FIELD_LENGTH

0x00008000 32768 FIELD_SCALE0x00010000 65536 FIELD_PROMPT0x00020000 131072 FIELD_SHORT_PROMPT0x00040000 262144 FIELD_HEADING0x00080000 524288 FIELD_FLAGS0x00100000 1048576 FIELD_DEFAULT0x00200000 2097152 FIELD_INPUT_LENGTH0x00400000 4194304 FIELD_OUTPUT_LENGTH0x00800000 8388608 FIELD_XML_FORMAT0x01000000 16777216 MS ADO.NET XML Format0x02000000 RESERVED0x04000000 RESERVED0x08000000 RESERVED0x10000000 RESERVED0x20000000 RESERVED0x40000000 RESERVED0x80000000 RESERVEDConnect 7.3 User Guide 1-19CON 7.3 UG 12/05


Flag value samples

DML example 1 The following example illustrates proper usage from within a DML stored procedure.EXTERNAL "gem_xmlpack.dll" SEND_XML_TABLE(DSTRING.D, LONG.V)CALL SEND_XML_TABLE("VRT_ORDERS3", 65537)Assuming that the VRT_ORDERS3 table contained no data, the following output would be produced.

field 1 prompt

field 2 prompt


Dec Hexadecimal Result-2 0xFFFFFFFE Include all table metadata.-1 0xFFFFFFFF Include all table data and metadata.1 0x000000001 Include table data only.

65537 0x000010001 Table data plus field prompt metadata.1-20 Connect 7.3 User GuideCON 7.3 UG 12/05


DML example 2 This example shows how multiple tables can be sent in the XML stream to the client. The sample sends two tables by coding two calls to SEND_XML_TABLE.EXTERNAL "gem_xmlpack.dll" SEND_XML_TABLE(DSTRING.D, LONG.V)CALL SEND_XML_TABLE("RENTALS", 1)CALL SEND_XML_TABLE("STATUS_MESSAGES_VT", 1)Since the flags parameter is set to 1 for both calls, only table data would be sent to the client there are not tags in the sample XML.

......

......

RECEIVE_XML_TABLES

The RECEIVE_XML_TABLES external procedure receives a stream of XML tables from the client. It accepts the following parameters:RECEIVE_XML_TABLES(message)Any error condition encountered by the XML parser is returned to the caller in the message parameter.

Important: At present, the RECEIVE_XML_TABLES external procedure should only be used for virtual tables. The reason for this is that the procedure empties all the contents of the table prior to receiving the new table data from the client. The stored procedure issuing the call can perform further data manipulations and/or move the received data from the virtual table to physical tables as desired after the data transfer is completed.

DML example The following example illustrates proper usage from within a DML stored procedure.EXTERNAL "gem_xmlpack.dll" RECEIVE_XML_TABLES(DSTRING.D)CALL RECEIVE_XML_TABLE(#MSG)Assuming for this example that the stored procedure expects data for the VT_XML_DEMO virtual table, the data can subsequently be moved to the XML_DEMO physical table after the data transfer is completed.XML_DEMO(FIELD1) = VT_XML_DEMO(FIELD1)XML_DEMO(FIELD2) = VT_XML_DEMO(FIELD2)XML_DEMO(FIELD3) = VT_XML_DEMO(FIELD3)ADD TO XML_DEMOConnect 7.3 User Guide 1-21CON 7.3 UG 12/05

New DML Commands

Two new DML commands are available as an alternative to using the EXTERNAL gem_xmlpack and the CALL command: SEND_XML_TABLE RECEIVE_XML_TABLES

Please see the DML manual for details.

Send XML Table DML Sample 1

EXTERNAL "gem_xmlpack.dll" SEND_XML_TABLE(DSTRING.D, LONG.V)CALL SEND_XML_TABLE("VRT_ORDERS3", 65537)Alternative:XML_SEND_TABLE VRT_ORDERS & /TABLE_OPTIONS="ALL" & /FIELD_OPTIONS=("NOALL,NAME,DATA_TYPE," & "INPUT_MASK,OUTPUT_MASK,MISSING," & "INITIAL_VALUE,COMPUTED_SOURCE," & "VALID_VALUES,DESCRIPTION," & "NUMBER,LENGTH,SCALE,PROMPT")

Send XML Table DML Sample 2

EXTERNAL "gem_xmlpack.dll" SEND_XML_TABLE(DSTRING.D, LONG.V)CALL SEND_XML_TABLE("RENTALS", 1)CALL SEND_XML_TABLE("STATUS_MESSAGES_VT", 1)Alternative:XML_SEND_TABLE RENTALS & /TABLE_OPTIONS="NOALL,DATA" & /FIELD_OPTIONS="NOALL"XML_SEND_TABLE STATUS_MESSAGES_VT & /TABLE_OPTIONS="NOALL,DATA" & /FIELD_OPTIONS="NOALL"

Receive XML Tables DML Sample

EXTERNAL "gem_xmlpack.dll" RECEIVE_XML_TABLES(DSTRING.D)CALL RECEIVE_XML_TABLE(#MSG)Alternative:XML_RECEIVE_TABLES /ERROR_TEXT=#MSG1-22 Connect 7.3 User GuideCON 7.3 UG 12/05

Sample Programs

Introduction The Connect distribution includes sample code to demonstrate the various uses of this technology. The demos have a similar underlying construction.

A client makes a request to a Connect application. A DML stored procedure is called on any supported IAF server machine. The stored procedure uses the new Connect gem_xmlpack to return XML-

formatted tables to the caller. The XML-formatted response is returned to the client.

procs.gem In order to run the demos, certain stored procedures delivered with Connect in the DML directory need to be applied against the server database. This task is simplified by using the supplied procs.gem DML program, which adds the required IAF metadata and the following stored procedures to your IAF database:XMLADDDATA.DMLXMLGETTABLE.DMLConnect 7.3 User Guide 1-23CON 7.3 UG 12/05

ContentsConnect 7.3 User GuideOverviewIntroductionChapter contentsConnect technologyWeb applicationsFramework classesIAF enterprise server

Web ApplicationsIntroductionSample usermap.config fileSample web.config filexpo.aspx parametersURL examplexmltable.aspx Web application parametersURL example

Connect ProgrammingIntroductionWeb servicesConnect ClassesError HandlingSwitching Usernames for a ConnectionADO.NET Dataset XML FormatPassing Tables as Stored procedure parametersRelated documents

IAF Enterprise ServerIntroductionAdditional requirementsRelated documentsgem_xmlpack librarySEND_XML_ TABLEFlag value samplesDML example 1DML example 2RECEIVE_XML _TABLESDML exampleNew DML CommandsSend XML Table DML Sample 1Send XML Table DML Sample 2Receive XML Tables DML Sample

Sample ProgramsIntroductionprocs.gem

ross iaf connect user guide 73

Documents