22.09.2013 Views

NetCOBOL for SPARC Architecture SAF Subroutines User's Guide

NetCOBOL for SPARC Architecture SAF Subroutines User's Guide

NetCOBOL for SPARC Architecture SAF Subroutines User's Guide

SHOW MORE
SHOW LESS

Create successful ePaper yourself

Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.

<strong>SAF</strong> <strong>Subroutines</strong><br />

User’s <strong>Guide</strong>


Ninth Edition: August 2008<br />

The contents of this manual may be revised without prior notice. No part of this document may<br />

be reproduced or transmitted in any <strong>for</strong>m or by any means, electronic or mechanical, <strong>for</strong> any<br />

purpose, without the express written permission of Fujitsu Limited.<br />

© 1996-2008 Fujitsu Limited. All Rights Reserved.


Preface<br />

This manual explains how to generate a COBOL program using <strong>NetCOBOL</strong> <strong>SAF</strong><br />

<strong>Subroutines</strong> 3.1, as well as how to execute the program and debug it.<br />

See also "<strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>" <strong>for</strong> creation, compilation, and execution of COBOL<br />

programs.<br />

For debugging of COBOL programs, see “<strong>NetCOBOL</strong> Debugging <strong>Guide</strong>”.<br />

See "<strong>NetCOBOL</strong> Language Reference" <strong>for</strong> syntax rules of COBOL.<br />

To generate a Web application that runs in Unicode, see also Appendix B in the<br />

"<strong>NetCOBOL</strong> Web <strong>Guide</strong>."<br />

Supported Environments<br />

<strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong> 3.1 run in 32-bit mode in the following systems and<br />

provides 32-bit development and operating environments <strong>for</strong> applications running<br />

with Netscape Enterprise Server 3.6 with SP3 or later or iPlanet Web Server<br />

Enterprise Edition 4.0 or later.<br />

•<br />

Microsoft® Windows® 2000 Server operating system<br />

• Microsoft® Windows® 2000 Advanced Server operating system<br />

Trademarks<br />

Trademarks mentioned in this manual are as follows:<br />

<strong>NetCOBOL</strong> is a trademark or registered trademark of Fujitsu Limited or its<br />

subsidiaries in the United States or other countries or in both.<br />

Microsoft and Windows are registered trademarks of Microsoft Corporation in the<br />

United States and other countries.<br />

Netscape, Netscape Navigator, and Netscape Enterprise Server are<br />

trademarks/registered trademarks of Netscape Communications Corporation in the<br />

United States and other countries.<br />

Other company names and product names are trademarks/registered trademarks of<br />

each company concerned.<br />

Permission <strong>for</strong> using screenshots was obtained from Microsoft Corporation, U.S.<br />

<strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong> <strong>User's</strong> <strong>Guide</strong> 3


Product Names<br />

Names of products described in this manual are abbreviated as:<br />

Product Name Abbreviation<br />

Microsoft® Windows® 2000 Server operating system Windows® 2000<br />

Microsoft® Windows® 2000 Advanced Server operating<br />

system<br />

Windows® 2000<br />

Microsoft® Internet Explorer IE<br />

Netscape Enterprise Server 3.6 with SP3 NES<br />

4 <strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong> <strong>User's</strong> <strong>Guide</strong>


Contents<br />

Chapter 1. <strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong> .......................................................7<br />

Overview of <strong>SAF</strong>................................................................................................. 7<br />

<strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong>................................................................................. 7<br />

Chapter 2. Creating Web Applications Using <strong>SAF</strong> <strong>Subroutines</strong>....................9<br />

Requirements....................................................................................................10<br />

What to Generate..............................................................................................10<br />

Using Assist Functions <strong>for</strong> Web Application Development ......................................13<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong>....................................................15<br />

<strong>SAF</strong> Subroutine Functions...................................................................................15<br />

<strong>SAF</strong> <strong>Subroutines</strong> Interface..................................................................................23<br />

Set the Work Environment and Acquire Web Parameter........................................24<br />

Manipulate Web Parameters...............................................................................25<br />

Output Processing Results..................................................................................28<br />

Execute System Commands................................................................................45<br />

Free <strong>SAF</strong> Execution Environment Resources.........................................................45<br />

Get Request In<strong>for</strong>mation....................................................................................46<br />

Manipulate Cookie Data .....................................................................................49<br />

Manipulate Uploaded Files..................................................................................55<br />

Manage Sessions...............................................................................................60<br />

<strong>SAF</strong>-Specific <strong>Subroutines</strong>....................................................................................64<br />

Data Length Restrictions of <strong>SAF</strong> <strong>Subroutines</strong>........................................................67<br />

Classes Provided by <strong>SAF</strong> <strong>Subroutines</strong> ..................................................................67<br />

Chapter 4. Generating and Executing a Web Application...........................69<br />

Executing a Web Application ..............................................................................70<br />

Compiling and Linking........................................................................................70<br />

NES Settings .....................................................................................................71<br />

Defining the Web Application to the <strong>SAF</strong> Director .................................................71<br />

Executing a Web Application ..............................................................................77<br />

<strong>SAF</strong> Director Reference ......................................................................................77<br />

<strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong> User’s <strong>Guide</strong> 5


Chapter 5. Debugging a <strong>SAF</strong> Application ...................................................81<br />

Referring to the Log In<strong>for</strong>mation ........................................................................82<br />

Checking Execution Using the Interactive Debugger .............................................82<br />

Displaying Errors Detected by <strong>SAF</strong> <strong>Subroutines</strong> ....................................................84<br />

Displaying Working-Storage Data or Messages in a Web Page...............................85<br />

Chapter 6. Samples ....................................................................................87<br />

Program Files Provided ......................................................................................88<br />

<strong>Subroutines</strong> Used ..............................................................................................88<br />

Program Compiling ............................................................................................88<br />

Program Linkage ...............................................................................................88<br />

Environment Setup ............................................................................................89<br />

Sample Execution..............................................................................................89<br />

Explanation of Samples......................................................................................89<br />

Appendix A. Frequently Asked Questions ..................................................97<br />

Appendix B. Error Recovery Processing...................................................105<br />

Appendix C. <strong>Architecture</strong> of a <strong>NetCOBOL</strong> <strong>SAF</strong> Application ......................113<br />

Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong> .........................115<br />

Conversion from CGI to <strong>SAF</strong> .............................................................................116<br />

Application Form .............................................................................................117<br />

Web Pages <strong>for</strong> Invoking Applications.................................................................117<br />

Compilation and Linking Methods......................................................................118<br />

Unit of Execution.............................................................................................118<br />

Compilation Method.........................................................................................119<br />

Accessing Common Resources..........................................................................119<br />

Server Interface Area.......................................................................................119<br />

Environment Variable Operations ......................................................................120<br />

Operations of CGI Environment Variables ..........................................................122<br />

6 <strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong> <strong>User's</strong> <strong>Guide</strong>


Chapter 1. <strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong><br />

Overview of <strong>SAF</strong><br />

<strong>SAF</strong> (Server Application Functions) is an application generated by using the NSAPI<br />

(Netscape Server Application Programming Interface).<br />

The NSAPI is an interface provided <strong>for</strong> extending the NES (Netscape Enterprise<br />

Server). <strong>SAF</strong> is included in the NES and runs as a thread so that it operates faster<br />

than CGI. It can save resource consumption including memory. Since <strong>SAF</strong> operates<br />

as a thread, however, the thread must be thread safe. If resources have not been<br />

released, you may not be able to use the resources until NES terminates, so caution<br />

must be taken.<br />

Browser<br />

Browser<br />

Request<br />

Response<br />

Request<br />

Response<br />

<strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong><br />

Process<br />

Thread<br />

<strong>SAF</strong><br />

Thread<br />

<strong>SAF</strong><br />

NSAPI<br />

The Web subroutines using NSAPI are called <strong>NetCOBOL</strong> <strong>SAF</strong> subroutines (hereafter,<br />

called <strong>SAF</strong> subroutines). The environment in which Web applications are generated<br />

by using <strong>SAF</strong> subroutines is called the <strong>NetCOBOL</strong> <strong>SAF</strong> director (hereafter, called <strong>SAF</strong><br />

director). The <strong>SAF</strong> director loads and executes Web applications generated by using<br />

the <strong>SAF</strong> subroutines. The Web applications are loaded when NES is started or at<br />

initial request, and the application resides in memory after that. The applications are<br />

not unloaded until NES is terminated.


8 Chapter 1. <strong>NetCOBOL</strong> <strong>SAF</strong> <strong>Subroutines</strong><br />

Browser<br />

NES<br />

Loads into<br />

the start<br />

time<br />

<strong>SAF</strong><br />

Director<br />

Loads into the<br />

start or access<br />

time<br />

COBOL<br />

Application<br />

The <strong>SAF</strong> director and the Web applications to be executed run as <strong>SAF</strong>s so that<br />

features of <strong>SAF</strong> are inherited by the Web applications. Since the <strong>SAF</strong> subroutines<br />

have higher-order compatibility than the CGI subroutines, Web applications that use<br />

CGI subroutines can be easily converted to Web applications under NES with some<br />

minor modifications.


Chapter 2. Creating Web Applications Using<br />

<strong>SAF</strong> <strong>Subroutines</strong><br />

This chapter describes how to use <strong>SAF</strong> subroutines to create web applications. It<br />

includes these topics:<br />

• System requirements<br />

• Resource requirements<br />

• How to use assist functions in the COBOL Project Manager


10 Chapter 2. Creating Web Applications Using <strong>SAF</strong> <strong>Subroutines</strong><br />

Requirements<br />

The following are required <strong>for</strong> creating <strong>SAF</strong> subroutine applications.<br />

• Netscape Enterprise Server 3.6with SP3 or later or iPlanet Web Server Enterprise<br />

Edition 4.0 or later required <strong>for</strong> executing the Web applications<br />

• Fujitsu COBOL V61L10 or later or <strong>NetCOBOL</strong> V7.0L10 or later required <strong>for</strong><br />

compiling, linking, and executing the Web applications<br />

When operating it, the <strong>NetCOBOL</strong> server operation package is necessary.<br />

Note: Ask the system administrator of your WWW server regarding the<br />

requirements of installing and setting up .<br />

What to Generate<br />

To generate <strong>SAF</strong> applications by using <strong>SAF</strong> subroutines, the following must be<br />

generated .<br />

• COBOL program to which any entry-name is assigned by using the <strong>SAF</strong><br />

subroutines and a resulting .DLL generated with the entry-name as an export<br />

function<br />

See Chapter 4 "Compiling and linking" <strong>for</strong> explanations of compiling and linking<br />

these programs.<br />

•<br />

HTML document<br />

- Web page <strong>for</strong> invoking each application (<strong>for</strong> starting the Web application)<br />

- Web page <strong>for</strong> processing result output (<strong>for</strong> returning processing results, to<br />

be generated on demand)<br />

Explanations of these items are given in the following sections.<br />

COBOL Programs using <strong>SAF</strong> <strong>Subroutines</strong><br />

It is possible to specify any name that can be specified in COBOL to the entry name<br />

of the COBOL program. To make this COBOL program operate as <strong>SAF</strong>, the <strong>SAF</strong><br />

subroutine must be used.<br />

Given below are requirements <strong>for</strong> generating COBOL programs that execute as <strong>SAF</strong><br />

applications.<br />

IDENTIFICATION DIVISION:<br />

None<br />

ENVIRONMENT DIVISION:<br />

None<br />

DATA DIVISION:<br />

• WORKING-STORAGE SECTION<br />

Include the <strong>SAF</strong> interface data area description by using a COPY statement.


WORKING-STORAGE SECTION.<br />

COPY COBW3<br />

Chapter 2. Creating Web Applications Using <strong>SAF</strong> <strong>Subroutines</strong> 11<br />

To use <strong>SAF</strong> specific functions, include the <strong>SAF</strong> specific data area.<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

COPY COBW3<strong>SAF</strong>. *>Interface with a <strong>SAF</strong> specific subroutine<br />

These libraries (COBW3.cbl and COBW3<strong>SAF</strong>.cbl) are stored in the folder in which<br />

Fujitsu <strong>NetCOBOL</strong> has been installed.<br />

• LINKAGE SECTION<br />

Define a pointer item <strong>for</strong> the interface with NES.<br />

LINKAGE SECTION.<br />

01 <strong>SAF</strong>CTX POINTER.<br />

PROCEDURE DIVISION<br />

Write the following in order to con<strong>for</strong>m to the calling conventions of NES.<br />

PROCEDURE DIVISION USING <strong>SAF</strong>CTX.<br />

<strong>SAF</strong>CTX obtained above is required <strong>for</strong> the <strong>SAF</strong> subroutines to communicate with<br />

NES, so initialize COBW3-CONTEXT as follows.<br />

MOVE LOW-VALUE TO COBW3.<br />

SET COBW3-CONTEXT TO <strong>SAF</strong>CTX.<br />

To use <strong>SAF</strong> specific functions, initialize COBW3-<strong>SAF</strong>-CONTEXT.<br />

MOVE LOW-VALUE TO COBW3<strong>SAF</strong>.<br />

SET COBW3-<strong>SAF</strong>-CONTEXT TO <strong>SAF</strong>CTX.<br />

Given the sample settings above, the skeleton of this program would appear as<br />

follows:<br />

IDENTIFICATION DIVISION.<br />

PROGRAM-ID. "<strong>SAF</strong>APL".<br />

ENVIRONMENT DIVISION.<br />

DATA DIVISION.<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

* COPY COBW3<strong>SAF</strong>.<br />

LINKAGE SECTION.<br />

01 <strong>SAF</strong>CTX POINTER.<br />

PROCEDURE DIVISION USING <strong>SAF</strong>CTX.<br />

*<br />

MOVE LOW-VALUE TO COBW3.<br />

* MOVE LOW-VALUE TO COBW3<strong>SAF</strong>.<br />

SET COBW3-CONTEXT TO <strong>SAF</strong>CTX.<br />

* SET COBW3-<strong>SAF</strong>-CONTEXT TO <strong>SAF</strong>CTX<br />

*<br />

* Write the process on demand.<br />

*<br />

EXIT PROGRAM.


12 Chapter 2. Creating Web Applications Using <strong>SAF</strong> <strong>Subroutines</strong><br />

Web Page <strong>for</strong> Invoking Application<br />

Prepare a normal HTML document. To start the Web application, however, use the<br />

tag or tag.<br />

Example:<br />

When executing the generated dynamic link library <strong>SAF</strong>.dll in METHOD = "POST"<br />

<br />

Note: When the Web application is started by using an tag, the Web<br />

parameter list cannot be obtained by the program.<br />

Make a setting on NES so that the extension “apl1” would correspond to <strong>SAF</strong> .dll<br />

containing the application. For details, see "NES setup" in Chapter 4 .<br />

For explanations concerning other HTML documents, see Appendix A of "<strong>NetCOBOL</strong><br />

Web <strong>Guide</strong>."<br />

Web Page <strong>for</strong> Processing Result Output<br />

The Web page <strong>for</strong> processing result output is an HTML document <strong>for</strong> returning the<br />

result of the Web application to the WWW browser. It is not necessary to create a<br />

Web page <strong>for</strong> processing result output because the response data, including the<br />

requisite HTML, can be returned directly from the Web application. If the Web page<br />

<strong>for</strong> processing result output is separate from the application program, however, then<br />

it is possible to change the layout of the output results without recompiling the Web<br />

application.<br />

To output the static HTML document (HTML document whose output data does not<br />

change due to process results), it is possible to use the HTML document generated<br />

with the HTML generation tool.<br />

It is also possible to dynamically change the <strong>for</strong>mat of the Web page <strong>for</strong> processing<br />

result output .<br />

Specifying the item name (conversion name) enclosed with "//COBOL//" on the<br />

output Web page enables dynamic data conversion . Since all data in an HTML<br />

document can be a target <strong>for</strong> replacement, it is also possible to replace a tag <strong>for</strong><br />

changing text or specifying the background color. For details, see<br />

"COBW3_PUT_HTML" in Chapter 3 "Processing result output."<br />

It is also possible to divide the title/statement/header into multiple HTML documents<br />

<strong>for</strong> output and to output the divided document in combination with plain text.<br />

Notes:<br />

• Do not use the following functions related to screen operation in the COBOL<br />

program to be used in the Web application. For details, see Chapter 21<br />

"Programs Running under a Service" in "<strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>."<br />

- Presentation file module (Screen handling module)<br />

- Screen handling module<br />

- ACCEPT/DISPLAY function<br />

(Modules handling environment variables, dates, and time, however, can be<br />

used.)


•<br />

•<br />

•<br />

•<br />

•<br />

Chapter 2. Creating Web Applications Using <strong>SAF</strong> <strong>Subroutines</strong> 13<br />

Be<strong>for</strong>e using <strong>SAF</strong> subroutines, the pointer item to be passed with the parameter<br />

must be set to COBW3-CONTEXT.<br />

The pointer item passed with COBW3, COBW3<strong>SAF</strong>, and the parameter must not<br />

be shared among multiple threads. NES may not operate normally.<br />

Do not specify REPLACING in the COPY statement that includes libraries<br />

(COBW3.cbl, COBW3<strong>SAF</strong>.cbl) provided by <strong>SAF</strong> subroutines. Do not write any<br />

REPLACE statement that may make the COPY statement a target <strong>for</strong> replacing.<br />

Do not modify the value of the pointer item passed with the parameter. If<br />

changed, the operation is not guaranteed.<br />

When the data is initialized (VALUE clause) in the DATA DIVISION, the initial<br />

value assigned <strong>for</strong> multiple requests is not guaranteed in some operating<br />

environments. If it is necessary to guarantee the initial value in every request<br />

from the WWW browser, the data must be initialized in the PROCEDURE<br />

DIVISION .<br />

Using Assist Functions <strong>for</strong> Web Application Development<br />

The COBOL Project Manager provides assist functions <strong>for</strong> Web application<br />

development.<br />

A COBOL program using <strong>SAF</strong> subroutines can be easily generated by using the Web<br />

application wizard of the COBOL Project Manager. Since the Web application<br />

wizard is linked to the Project Manager, it is also possible to compile/link/maintain<br />

the generated program.<br />

For details of assist functions <strong>for</strong> Web application development, see "Web<br />

Development Tools <strong>Guide</strong>."


14 Chapter 2. Creating Web Applications Using <strong>SAF</strong> <strong>Subroutines</strong>


Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

This chapter lists and describes each of the <strong>NetCOBOL</strong> <strong>SAF</strong> subroutines.<br />

<strong>SAF</strong> Subroutine Functions<br />

The <strong>SAF</strong> subroutines provide functions as follows:<br />

Basic Functions<br />

These are the basic functions used in creating a <strong>NetCOBOL</strong> <strong>SAF</strong> Web application.<br />

Function Subroutine name Usage<br />

Setting the work<br />

environment and getting<br />

the Web parameter<br />

Web parameter operation<br />

Processing result output<br />

COBW3_INIT Setting the work environment <strong>for</strong> <strong>SAF</strong><br />

subroutines and getting the Web parameter<br />

COBW3_GET_VALUE Searching NAME in the Web parameter and<br />

COBW3_GET_VALUE_XX<br />

getting VALUE<br />

COBW3_GET_VALUE_NX<br />

COBW3_GET_VALUE_XN<br />

COBW3_GET_VALUE_NN<br />

COBW3_CHECK_VALUE Searching VALUE in the Web parameter<br />

COBW3_CHECK_VALUE_X<br />

COBW3_CHECK_VALUE_N<br />

COBW3_PUT_HEAD Header output<br />

COBW3_PUT_HTML Outputting the Web page <strong>for</strong> processing<br />

result output<br />

COBW3_SET_CNV<br />

Setting the converted data in the Web page<br />

COBW3_SET_CNV_XX<br />

<strong>for</strong> processing result output<br />

COBW3_SET_CNV_NX<br />

COBW3_SET_CNV_XN<br />

COBW3_SET_CNV_NN<br />

COBW3_DEL_CNV<br />

Deleting the converted data in the Web page<br />

COBW3_DEL_CNV_X<br />

<strong>for</strong> processing result output<br />

COBW3_DEL_CNV_N<br />

COBW3_INIT_CNV Initializing the converted data in the Web<br />

page <strong>for</strong> processing result output<br />

COBW3_SET_REPEAT Setting the repeated conversion data in the<br />

COBW3_SET_REPEAT_XX<br />

Web page <strong>for</strong> processing result output<br />

COBW3_SET_REPEAT_NX<br />

COBW3_SET_REPEAT_XN<br />

COBW3_SET_REPEAT_NN


16 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Processing result output<br />

System command<br />

execution<br />

Releasing resources of<br />

<strong>SAF</strong> execution<br />

environment<br />

Getting request<br />

in<strong>for</strong>mation<br />

Cookie data operation<br />

COBW3_DEL_REPEAT Deleting the repeated conversion data in the<br />

COBW3_DEL_REPEAT_X<br />

COBW3_DEL_REPEAT_N<br />

Web page <strong>for</strong> processing result output<br />

COBW3_INIT_REPEAT Initializing the repeated conversion data in<br />

the Web page <strong>for</strong> processing result output<br />

COBW3_PUT_TEXT Data output (line feed code added)<br />

COBW3_SYSTEM Executing the system command specified<br />

COBW3_FREE Releasing resources obtained by the <strong>SAF</strong><br />

subroutine<br />

COBW3_RECEIVE_HEADER Getting the HTTP header<br />

COBW3_GET_REQUEST_INF Getting in<strong>for</strong>mation related to requests<br />

O<br />

COBW3_GET_AUTHORIZE Getting authorization in<strong>for</strong>mation<br />

COBW3_SET_COOKIE Setting Cookie data<br />

COBW3_SET_COOKIE_XX<br />

COBW3_SET_COOKIE_NX<br />

COBW3_SET_COOKIE_XN<br />

COBW3_SET_COOKIE_NN<br />

COBW3_DEL_COOKIE Deleting Cookie data that has been set<br />

COBW3_DEL_COOKIE_X<br />

COBW3_DEL_COOKIE_N<br />

COBW3_INIT_COOKIE Initializing all Cookie data that has been set<br />

COBW3_GET_COOKIE Getting Cookie data with the Web parameter<br />

COBW3_GET_COOKIE_XX<br />

COBW3_GET_COOKIE_NX<br />

COBW3_GET_COOKIE_XN<br />

COBW3_GET_COOKIE_NN<br />

• It is necessary to use the following subroutines in an ASCII environment.<br />

COBW3_GET_VALUE<br />

COBW3_CHECK_VALUE<br />

COBW3_SET_CNV<br />

COBW3_DEL_CNV<br />

COBW3_SET_REPEAT<br />

COBW3_DEL_REPEAT<br />

COBW3_SET_COOKIE<br />

COBW3_DEL_COOKIE<br />

COBW3_GET_COOKIE


• In the Unicode environment, use the following subroutines:<br />

•<br />

Subroutine name Explanation<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 17<br />

COBW3_xxxxx_XX Both NAME and VALUE parameters are regarded as alphanumeric<br />

data items.<br />

COBW3_xxxxx_NX NAME parameter is regarded as a national data item and VALUE<br />

parameter is regarded as an alphanumeric data item.<br />

COBW3_xxxxx_XN NAME parameter is regarded as an alphanumeric data item and<br />

VALUE parameter is regarded as a national data item.<br />

COBW3_xxxxx_NN Both NAME and VALUE parameters are regarded as national data<br />

items.<br />

COBW3_xxxxx_X The Input parameter is regarded as an alphanumeric data item.<br />

COBW3_xxxxx_N The Input parameter is regarded as a national data item.<br />

Any code system can use the <strong>SAF</strong> subroutines not listed above.<br />

File Upload Function<br />

The file upload function transfers client-side-generated data (files) to the server.<br />

This function is valid in the following cases:<br />

• When a large amount of data which may cause timer expiration in online<br />

processing is to be entered.<br />

• When a mobile environment with meter-rate accounting is to be used.<br />

• When a data entry tool is already prepared at the client side and server linkage<br />

using the tool output data (files) is requested instead of a request to change the<br />

data entry tool into a Web tool.<br />

• When only the HTTP ports can be accessed in file transfer because of security<br />

conditions. (File transfer in conventional systems is done using FTP.)<br />

Using the file upload function, file transfer can be associated with applications.<br />

There<strong>for</strong>e, data can be checked and registered immediately after file transfer.


18 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Client<br />

File upload processing is shown below:<br />

File-A<br />

C:\ File-A Browse<br />

Registration<br />

completion!!<br />

Send<br />

Server<br />

Set of name of file to be transferred<br />

WWW<br />

Server<br />

: Processing flow<br />

Web Application<br />

Acquisition of upload<br />

file in<strong>for</strong>mation<br />

Generation of file<br />

Extraction of data<br />

from file<br />

Registration of extracted<br />

data into DB<br />

Deletion of file<br />

:<br />

Uploaded File-A<br />

Database<br />

Function provided by Web<br />

subroutines


Web page <strong>for</strong> invoking the applications<br />

:<br />

<br />

<br />

Send file:<br />

<br />

<br />

<br />

:<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 19<br />

Web application (COBOL source)<br />

:<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

PROCEDURE DIVISION.<br />

*<br />

CALL “COBW3_INIT” USING COBW3.<br />

*<br />

*GET INFORMATION OF UPLOADED FILE<br />

MOVE “UPFILE” TO<br />

COBW3-SEARCH-DATA.<br />

CALL “COBW3_GET_UPLOADFILE_INFO”<br />

USING COBW3.<br />

IF COBW3-SEARCH-FLAG-NON THEN<br />

Error Processing<br />

END-IF.<br />

*SET GENERATION FILE-NAME<br />

MOVE “File-A” TO<br />

COBW3-UPLOADED-FILENAME.<br />

CALL “COBW3_GEN_UPLOADFILE”<br />

USING COBW3.<br />

IF COBW3-STATUS NOT = ZERO THEN<br />

Error Processing<br />

END-IF.<br />

*************************************************<br />

*<br />

* Any processing <strong>for</strong> uploaded files<br />

*<br />

*************************************************<br />

*DELETION UPLOADED FILES<br />

CALL “COBW3_DEL_UPLOADFILE”<br />

USING COBW3.<br />

CALL “COBW3_PUT_HTML”<br />

USING COBW3.<br />

CALL “COBW3_FREE” USING COBW3.


20 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Web subroutines provide the following functions to easily create such application<br />

programs:<br />

Function Subroutine name Usage<br />

File upload COBW3_GET_UPLOADFILE_INFO Acquires the in<strong>for</strong>mation on an<br />

COBW3_GET_UPLOADFILE_INFO_X<br />

COBW3_GET_UPLOADFILE_INFO_N<br />

upload file.<br />

COBW3_GEN_UPLOADFILE<br />

Generates an uploaded file on the<br />

COBW3_GEN_UPLOADFILE_X<br />

COBW3_GEN_UPLOADFILE_N<br />

server.<br />

COBW3_DEL_UPLOADEDFILE Deletes an uploaded file.<br />

To upload a file, the following values must be written on the Web page <strong>for</strong> invoking<br />

an application:<br />

Tag name Attributes Value<br />

FORM<br />

METHOD POST<br />

ENCTYPE multipart/<strong>for</strong>m-data<br />

INPUT TYPE file<br />

For details of these tags and attributes, see the “<strong>NetCOBOL</strong> Web <strong>Guide</strong>” and other<br />

documents or home pages that explain HTML.<br />

The above tags can be used together with the INPUT tag of other types (that is,<br />

other than “file”) in the same FORM. The data that corresponds to these INPUT tags<br />

can be acquired by a subroutine such as COBW3_GET_VALUE regardless of whether<br />

the file upload function is used.<br />

Note: The NAME value specified in the INPUT tag (TYPE=”file”) <strong>for</strong> uploading files<br />

cannot be used in the INPUT tag of other types (that is, other than “file”).<br />

Otherwise, the normal operation of the Web subroutine is not assured.<br />

For example:<br />

:<br />

<br />

Do not specify<br />

:


Session Management Functions<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 21<br />

Using the session management functions enables Web applications to handle<br />

multiple requests from a specific client session (WWW browser).<br />

Function Subroutine name Usage<br />

Session<br />

COBW3_START_SESSION Starting the session<br />

management<br />

COBW3_END_SESSION Terminating the session<br />

COBW3_SET_SESSION_DATA Setting the session data<br />

COBW3_GET_SESSION_DATA Getting the session data<br />

COBW3_ALTER_SESSION_TIME<br />

OUT<br />

Changing the time of session timeout<br />

COBW3_GET_SESSION_INFO Getting the current session<br />

in<strong>for</strong>mation<br />

The session management functions cannot be used with COBOL CGI subroutines.<br />

It is possible to maintain the connection status with a specific client (WWW browser)<br />

by using the session management functions <strong>for</strong> opening the session. In a single<br />

session, the data entered on a previous page can be inherited by a subsequent page<br />

using the session data functions.<br />

WWW Browser WWW Server<br />

Screen1<br />

Screen2<br />

Screen3<br />

Web<br />

Application 1<br />

Web<br />

Application 2<br />

Session data<br />

is inherited<br />

Session<br />

start<br />

Session<br />

end<br />

A session time-out occurs when the client session transmits no data <strong>for</strong> an extended<br />

period or when the transaction is interrupted due to some reason such as the WWW<br />

browser being closed be<strong>for</strong>e completing the session .<br />

A time-out occurs when the time counted from when the Web application returned a<br />

response to the WWW browser to when the next request is issued by the WWW<br />

browser in the same session has exceeded the specified time. When a time-out<br />

occurs, the session management terminates the session leaving the application’s<br />

resources in the same status as when the session was interrupted . To cope with<br />

such a status, the session management functions provide a registration mechanism<br />

of time-out processing.


22 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

WWW Browser WWW Server<br />

Screen1<br />

Screen2<br />

Note: If multiple Web applications using the session are started by double-clicking a<br />

button <strong>for</strong> which SUBMIT is specified as the TYPE attribute of the INPUT tag, the<br />

applications will not operate properly. The programmer should prevent the<br />

inadvertent starting of multiple applications by using JavaScript in the WWW<br />

browser. See "<strong>NetCOBOL</strong> Web <strong>Guide</strong>" <strong>for</strong> general notes on WWW browser<br />

operation.<br />

<strong>SAF</strong>-Specific Functions<br />

After a long time<br />

passes, access to the<br />

Web application<br />

Web<br />

Application 1<br />

TIMEOUT<br />

Web<br />

Application 2<br />

<strong>SAF</strong> specific functions enable getting in<strong>for</strong>mation specifically related to NES .<br />

Listed below are <strong>SAF</strong> specific subroutines.<br />

Function Subroutine name Usage<br />

Getting NES setting COBW3_<strong>SAF</strong>_GET_PARM Getting the parameter specified to<br />

COBW3_<strong>SAF</strong>_GET_PARM_XX<br />

COBW3_<strong>SAF</strong>_GET_PARM_NX<br />

COBW3_<strong>SAF</strong>_GET_PARM_XN<br />

COBW3_<strong>SAF</strong>_GET_PARM_NN<br />

the <strong>SAF</strong> director<br />

Getting request COBW3_<strong>SAF</strong>_GET_BASENAME Getting the application name<br />

in<strong>for</strong>mation<br />

specified to the URL<br />

Note: Use the following subroutine in an ASCII environment:<br />

COBW3_<strong>SAF</strong>_GET_PARAM<br />

Session<br />

start<br />

Timeout<br />

processing<br />

Session data<br />

is <strong>for</strong>ced<br />

Session data<br />

cannot be<br />

inherited


<strong>SAF</strong> <strong>Subroutines</strong> Interface<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 23<br />

This section explains the calling interface <strong>for</strong> using the <strong>SAF</strong> subroutines.<br />

Note: It is possible to check errors and warning in the <strong>SAF</strong> subroutines by referring<br />

to COBW3-STATUS, and those in <strong>SAF</strong> specific subroutines by referring to COBW3-<br />

<strong>SAF</strong>-STATUS.<br />

Value Meaning<br />

0 Normal end<br />

Not zero Error number<br />

See Appendix B "Error Recovery Processing" <strong>for</strong> error numbers.<br />

Library<br />

The library file is a COPY member <strong>for</strong> use as a <strong>SAF</strong> data area. When calling <strong>SAF</strong><br />

subroutines, include the following library file in the Working-Storage Section with a<br />

COPY statement. This library file is stored in the folder in which Fujitsu <strong>NetCOBOL</strong><br />

has been installed.<br />

Library name: COBW3.cbl<br />

Format: Specify as follows:<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

To call <strong>SAF</strong> specific subroutines, include the <strong>SAF</strong> specific data area using the COPY<br />

statement. This library is also stored in the folder to which Fujitsu <strong>NetCOBOL</strong> has<br />

been installed.<br />

Library name: COBW3<strong>SAF</strong>.cbl<br />

Format: Specify as follows:<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

COPY COBW3<strong>SAF</strong>. *> Interface with a <strong>SAF</strong> specific subroutine<br />

Note: Do not specify REPLACING in the COPY statement of a <strong>SAF</strong> data area or write<br />

a REPLACE statement that might make the COPY statement a target <strong>for</strong> replacing.<br />

If names in the <strong>SAF</strong> data area are changed, the operation is not guaranteed.<br />

Calling <strong>SAF</strong> <strong>Subroutines</strong><br />

In order to initialize the environment of the <strong>SAF</strong> subroutines and to get the Web<br />

page parameter list, it is necessary to call COBW3_INIT be<strong>for</strong>e calling any other <strong>SAF</strong><br />

function. When terminating the processing <strong>for</strong> <strong>SAF</strong> subroutines, COBW3_FREE must<br />

be called to release resources acquired by the <strong>SAF</strong> subroutines.<br />

When calling other subroutines from a program that is not the one which called<br />

COBW3_INIT, the interface area (COBW3) defined in the program which called<br />

COBW3_INIT is shared among programs.


24 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Example: Calling COBW3_INIT by the parent program and calling COBW3_FREE by<br />

the child program B.<br />

Parent program<br />

IDENTIFICATION DIVISION.<br />

PROGRAM-ID. "MainProc".<br />

DATA DIVISION.<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

LINKAGE SECTION.<br />

01 <strong>SAF</strong>CTX POINTER.<br />

PROCEDURE DIVISION USING <strong>SAF</strong>CTX.<br />

MOVE LOW-VALUE TO COBW3.<br />

MOVE <strong>SAF</strong>CTX TO COBW3-CONTEXT.<br />

CALL "COBW3_INIT" USING COBW3.<br />

:<br />

CALL "B" USING COBW3<br />

*<br />

EXIT PROGRAM.<br />

Child program<br />

IDENTIFICATION DIVISION.<br />

PROGRAM-ID. B.<br />

DATA DIVISION.<br />

LINKAGE SECTION.<br />

COPY COBW3<br />

PROCEDURE DIVISION USING COBW3.<br />

:<br />

CALL "COBW3_FREE" USING COBW3.<br />

EXIT PROGRAM.<br />

Set the Work Environment and Acquire Web Parameter<br />

COBW3_INIT<br />

Set the work environment <strong>for</strong> <strong>SAF</strong> subroutines. Get a Web parameter and set it to<br />

the work area to be used by <strong>SAF</strong> subroutines.<br />

Note: Initialize COBW3 in the interface area with LOW-VALUE be<strong>for</strong>e calling<br />

COBW3_INIT.<br />

Format:<br />

CALL "COBW3_INIT" USING COBW3.<br />

COBW3 Data <strong>for</strong> Call:<br />

•<br />

•<br />

COBW3-CONTEXT [required]<br />

Specify the Linkage Section pointer to the data work area with the <strong>SAF</strong> director.<br />

Do not change the specified value.<br />

COBW3-DMODE [optional]<br />

Specify error message output of <strong>SAF</strong> subroutines.<br />

COBW3-DMODE is valid only when the operation code is ASCII.


Condition-name Value Meaning<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 25<br />

COBW3-DMODE-NODBG LOW-VALUE No error message is output.<br />

COBW3-DMODE-DBG "1" An error message is output to the browser.<br />

Processing Result Data:<br />

None.<br />

Note: If COBW3_INIT is called more than once per connection, the Web data area<br />

obtained may be reinitialized and subsequent operations may fail.<br />

Manipulate Web Parameters<br />

COBW3_GET_VALUE, COBW3_GET_VALUE_XX,<br />

COBW3_GET_VALUE_NX, COBW3_GET_VALUE_XN,<br />

COBW3_GET_VALUE_NN<br />

Search a field name (NAME) from the Web parameter obtained in COBW3_INIT and<br />

return the value (VALUE) corresponding to the name.<br />

ASCII environment:<br />

• COBW3_GET_VALUE<br />

Search the name (NAME) of an alphanumeric character-string and return the<br />

value (VALUE) corresponding to the name as an alphanumeric character-string.<br />

Unicode environment:<br />

• COBW3_GET_VALUE_XX<br />

Search the name (NAME) of an alphanumeric character-string and return the<br />

value (VALUE) corresponding to the name as an alphanumeric character-string.<br />

• COBW3_GET_VALUE_NX<br />

Search the name (NAME) of a national character-string and return the value<br />

(VALUE) corresponding to the name as an alphanumeric character-string.<br />

• COBW3_GET_VALUE_XN<br />

Search the name (NAME) of a alphanumeric character-string and return the<br />

value (VALUE) corresponding to the name as a national character-string.<br />

• COBW3_GET_VALUE_NN<br />

Search the name (NAME) of a national character-string and return the value<br />

(VALUE) corresponding to the name as a national character-string.<br />

Padding characters <strong>for</strong> storing the obtained value (VALUE) are blank.<br />

Format:<br />

CALL "COBW3_GET_VALUE" USING COBW3.


26 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

•<br />

•<br />

CALL "COBW3_GET_VALUE_XX" USING COBW3.<br />

CALL "COBW3_GET_VALUE_NX" USING COBW3.<br />

CALL "COBW3_GET_VALUE_XN" USING COBW3.<br />

CALL "COBW3_GET_VALUE_NN" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:COBW3-SEARCH-DATA, COBW3-SEARCH-DATA-N<br />

Specify the name (NAME) to be searched. (The name is the value specified as a<br />

name in the HTML document that invokes the application.)<br />

Set to COBW3-SEARCH-DATA <strong>for</strong> COBW3_GET_VALUE, COBW3_GET_VALUE_XX<br />

and COBW3_GET_VALUE_XN.<br />

Set to COBW3-SEARCH-DATA-N <strong>for</strong> COBW3_GET_VALUE_NX or<br />

COBW3_GET_VALUE_NN.<br />

COBW3-SEARCH-LENGTH [Optional]<br />

To search a name (NAME) containing a valid space at the end, set this to the<br />

character-string length (byte length) of the name containing the space.<br />

Value Meaning<br />

0 Search up to the last character that is not a space.<br />

1 to 1024 Search up to the length of the character-string specified.<br />

• COBW3-NUMBER [Optional]<br />

If two or more same names (NAME) exist in the web data area, set the<br />

occurrence number of the target name to be searched .<br />

Condition-name Value Meaning<br />

COBW3-NUMBER-INIT 1 Search the first name that matches.<br />

- - - - - 2 to 9999 Search the specified occurrence of the name.<br />

Processing Result Data:<br />

• COBW3-SEARCH-FLAG<br />

Condition-name Value Meaning<br />

COBW3-SEARCH-FLAG<br />

-NON<br />

"0" The target name <strong>for</strong> searching is not found.<br />

COBW3-SEARCH-FLAG<br />

-EXIST<br />

"1" The target name <strong>for</strong> searching is found.


•<br />

•<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 27<br />

COBW3-GET-DATA, COBW3-GET-DATA-N<br />

The value (VALUE) corresponding to the name (NAME) is set.<br />

Set to COBW3-GET-DATA <strong>for</strong> COBW3_GET_VALUE, COBW3_GET_VALUE_XX and<br />

COBW3_GET_VALUE_NX.<br />

Set to COBW3-GET-DATA-N <strong>for</strong> COBW3_GET_VALUE_XN or<br />

COBW3_GET_VALUE_NN.<br />

COBW3-GET-LENGTH<br />

The character-string length (byte length) of the value (VALUE) corresponding to<br />

name (NAME) to be searched is set.<br />

COBW3_CHECK_VALUE, COBW3_CHECK_VALUE_X,<br />

COBW3_CHECK_VALUE_N<br />

Search <strong>for</strong> a value (VALUE) in the Web data area obtained in COBW3_INIT. This<br />

subroutine is used <strong>for</strong> determining the presence of a selected check box item in the<br />

data area from the Web page<br />

ASCII environment:<br />

• COBW3_CHECK_VALUE<br />

Search the value (VALUE) of an alphanumeric character-string.<br />

Unicode environment:<br />

• COBW3_CHECK_VALUE_X<br />

Search the value (VALUE) of an alphanumeric character-string.<br />

• COBW3_CHECK_VALUE_N<br />

Search the value (VALUE) of a national character-string.<br />

Format:<br />

CALL "COBW3_CHECK_VALUE" USING COBW3.<br />

CALL "COBW3_CHECK_VALUE_X" USING COBW3.<br />

CALL "COBW3_CHECK_VALUE_N" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-SEARCH-DATA and COBW3-SEARCH-DATA-N<br />

Set a value to be searched <strong>for</strong>.<br />

Set the value in COBW3-SEARCH-DATA if it is COBW3_CHECK_VALUE or<br />

COBW3_CHECK_VALUE_X.<br />

Set the value in COBW3-SEARCH-DATA-N if it is COBW3_CHECK_VALUE_N.


28 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

• COBW3-SEARCH-LENGTH [Optional]<br />

Set the character length of a value with a valid space at the end to the number<br />

of bytes including the space.<br />

Value Meaning<br />

0 The length to the last character, excluding the space, is checked.<br />

1 to 1024 Values of the specified character length are searched <strong>for</strong>.<br />

• COBW3-NUMBER [Optional]<br />

Set the sequential order of a value to be searched <strong>for</strong> if there are several<br />

equivalent values in the web parameter.<br />

Condition-name Value Meaning<br />

COBW3-NUMBER-INIT 1 The value found first is selected.<br />

- - - - - 2 to 9999 The value of the specified occurrence is<br />

searched <strong>for</strong>.<br />

Processing Result Data:<br />

• COBW3-SEARCH-FLAG<br />

Condition-name Value Meaning<br />

COBW3-SEARCH-FLAG<br />

-NON<br />

"0" No applicable values exist.<br />

COBW3-SEARCH-FLAG<br />

-EXIST<br />

"1" Applicable values exist.<br />

Output Processing Results<br />

COBW3_PUT_HEAD<br />

This subroutine outputs a specified header.<br />

When an HTML document designed <strong>for</strong> processing result output (prototype file) is<br />

used, the header is output using the text/html <strong>SAF</strong> subroutine. Thus, it is<br />

unnecessary to use this subroutine to output the header. Use this subroutine only to<br />

output an non HTML document file (such as a plane text) or application generated<br />

header.<br />

Note: Use this subroutine be<strong>for</strong>e using COBW3_PUT_HTML or COBW3 PUT TEXT.<br />

If it is used after COBW3_PUT_HTML or COBW3_PUT_TEXT, the in<strong>for</strong>mation<br />

becomes invalid as a header.<br />

Do not change the value after a non-default value is set in COBW3-CONTENT-TYPE<br />

or COBW3-STATUS-CODE.<br />

Format:<br />

CALL “COBW3_PUT_HEAD” USING COBW3.


Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 29<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-PUT-HEAD<br />

Set a character string to be output to the header.<br />

• COBW3-PUT-HEAD-LENGTH [Optional]<br />

Set the length of a character string with a valid space at the end to the number<br />

of bytes including the space.<br />

Value Meaning<br />

0 Character strings of any length, excluding terminating at the first space, are<br />

output. However, the character length is regarded as 0 (i.e., line feed<br />

character only) if COBW3-PUT-HEAD is filled with spaces only.<br />

1 to 512 Character strings of the specified character length are output.<br />

• COBW3- CONTENT-TYPE [Optional]<br />

Set a file type (Content-type) of response data.<br />

When this subroutine is called several times, the first file type is used.<br />

Condition-name Value Meaning<br />

- - - - - LOW-VALUE An HTML document is output.<br />

COBW3-CONTENT-TYPE<br />

-NON<br />

HIGH-VALUE Content-type is not output.<br />

COBW3-CONTENT-TYPE<br />

-HTML<br />

“text/htm1” An HTML document is output.<br />

COBW3-CONTENT-TYPE<br />

-TEXT<br />

“text/plain” A text file is output.<br />

- - - - - - - - Any character Any character string is set in Content-type<br />

string<br />

of the header.<br />

• COBW3-STATUS-CODE [Optional]<br />

Set status code.<br />

When this subroutine is called several times, the first status code is validated.<br />

Condition-name Value Meaning<br />

- - - - - - - - LOW-VALUE The normal end code "200" is output to<br />

Status-code.<br />

COBW3-STATUS-CODE<br />

-NON<br />

HIGH-VALUE Status-code is not output.<br />

COBW3-STATUS-CODE<br />

–200<br />

“200” The normal end code "200" is output to<br />

Status-code.<br />

- - - - - - - - Any code Any status-code is output.<br />

Note: If possible, do not specify COBW3-CONTENT-TYPE-NON or COBW3-STATUS-<br />

CODE-NON . "-NON" is meaningful <strong>for</strong> CGI, which enables Content-type, etc. to be<br />

specified using a batch file. However, <strong>SAF</strong> or other DLL applications do not accept -<br />

NON specification. In addition, operation of <strong>SAF</strong> is indefinite if Content-type or<br />

Status-code is not set though -NON is specified.


30 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

COBW3_PUT_HTML<br />

This subroutine outputs a prototype HTML page <strong>for</strong> processing the <strong>NetCOBOL</strong> <strong>SAF</strong><br />

result data area. It replaces conversion names enclosed in "//COBOL//" or<br />

"//COBOL_REPEAT//" in the Web page with character strings registered using the<br />

COBW3_SET_CNV_XX or COBW3_SET_REPEAT_XX subroutine<br />

Format:<br />

CALL “COBW3_PUT_HTML” USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-HTML-FILENAME<br />

Specify the file name of the Web page <strong>for</strong> processing result output (prototype<br />

file).<br />

Processing Result Data:<br />

None.<br />

Specification of a Conversion Name in the Web Page (prototype file):<br />

Enclose the conversion field name in "//COBOL//" to indicate that the character string<br />

is a conversion name.<br />

Note: A set of "//COBOL//" must be written on a single line.<br />

···//COBOL// Conversion name//COBOL//···<br />

Format of the output depends on the conversion name specifications. For example:<br />

Examples:<br />

Conversion name specification Processing<br />

This is a<br />

If a conversion name "NAME" is specified,<br />

//COBOL//NAME//COBOL// test.<br />

"//COBOL//NAME//COBOL//" is converted into a<br />

registered conversion character string.<br />

This is a //COBOL// test. The conversion name is incorrectly specified and will<br />

result in an error.<br />

This is a //COBOL test. This will be output as plain text.<br />

This is a //COBOL//<br />

The conversion name is incorrectly specified (more<br />

NAME//COBOL// test.<br />

than one line)<br />

This is a<br />

The conversion name is incorrectly specified (second<br />

//COBOL//NAME//COBOL<br />

//COBOL//)<br />

This is a<br />

//COBOL////COBOL//<br />

The conversion name is missing, resulting in an error.<br />

This is a<br />

This will be output as plain text, due to the incorrect<br />

//cobol//NAME//cobol// .<br />

use of lower case in the flags.


Application example:<br />

[a.htm (Web page prototype file)]<br />

:<br />

<br />

<br />

Name: //COBOL//GET-NAME//COBOL//<br />

<br />

:<br />

[COBOL program]<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 31<br />

:<br />

* Specifying a name<br />

MOVE “GET-NAME” TO COBW3-CNV-NAME.<br />

MOVE “FUJITSU TARO” TO COBW3-CNV-VALUE.<br />

* Specifying conversion data to be repeated in the Wed page <strong>for</strong><br />

* processing result output (prototype file)<br />

CALL “COBW3_SET_CNV” USING COBW3<br />

:<br />

* Specifying the file name of the Web page <strong>for</strong> processing result<br />

* output (prototype file)<br />

MOVE “a.htm” TO COBW3-HTML-FILENAME.<br />

* Outputting the Web page <strong>for</strong> processing result output (prototype<br />

* file)<br />

CALL “COBW3_PUT_HTML” USING COBW3<br />

:<br />

[Output result on the WWW browser]<br />

:<br />

Name: FUJITSU TARO<br />

:<br />

Specification of a Repetition Range in the Web Page Prototype File:<br />

Write "//COBOL_REPEAT_START//" and "//COBOL_REPEAT_END//" be<strong>for</strong>e and after<br />

a part in the Web page prototype file to specify that the part should be repeated.<br />

The number of times of repetition is identical to the number of registered repetitive<br />

character strings to be converted.<br />

• Beginning of the repetition range<br />

Write "//COBOL_REPEAT_START//" at the beginning of the range.<br />

• Repetition data<br />

Write data to be output repeatedly. If data should be converted when the Web<br />

application is executed, specify conversion names.<br />

If a different conversion character string should be output in each separate<br />

repetition cycle, write "//COBOL_REPEAT//" be<strong>for</strong>e and after each conversion<br />

name. If a separate conversion character string should be output in every<br />

repetition, write "//COBOL//" be<strong>for</strong>e and after conversion name.


32 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

• End of the repetition range<br />

Write "//COBOL_REPEAT_END//" at the end of the range where data should be<br />

repeated.<br />

Note: Be sure to register each conversion character string corresponding to the<br />

conversion name enclosed in "//COBOL_REPEAT//" .<br />

If a conversion name enclosed in "//COBOL_REPEAT//" is not written as repetition<br />

data, the number of times of repetition is 1.<br />

"//COBOL//" or "//COBOL_REPEAT//" must be written on a single line.<br />

Each line containing "//COBOL_REPEAT_START" or "//COBOL_REPEAT_END//""<br />

indicating the beginning and end of a repetition range is deleted when data is output<br />

to the WWW browser. There<strong>for</strong>e, do not write anything else on such a line.<br />

The numbers of repetitive conversion character strings specified in a repetition range<br />

must match the number of repetitions of the data or an error occurs.<br />

If the beginning of a repetition range is not specified, data output is not repeated<br />

and descriptions other than "//COBOL//" are output as data.<br />

If the end of a repetition range is not specified, data up to the end of the Web page<br />

is output and an error occurs.<br />

//COBOL_REPEAT_START//<br />

· ·//COBOL_REPEAT// Conversion name//COBOL_REPEAT//· ·<br />

· ·//COBOL// Conversion name// COBOL//· ·<br />

//COBOL_REPEAT_END//<br />

Application example:<br />

[b.htm. (Web page <strong>for</strong> processing result output (prototype file)]<br />

<br />

<br />

Name<br />

Age<br />

Company<br />

<br />

//COBOL_REPEAT_START//<br />

<br />

//COBOL_REPEAT//GET-NAME//COBOL_REPEAT//<br />

//COBOL_REPEAT//GET-AGE//COBOL_REPEAT//<br />

//COBOL//GET-OFFICE//COBOL//<br />

<br />

//COBOL_REPEAT_END//<br />

<br />

:


[COBOL program]<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 33<br />

:<br />

PERFORM UNTIL END-FLAG=”END”<br />

* Specifying a name<br />

MOVE “GET-NAME” TO COBW3-CNV-NAME<br />

MOVE Name TO COBW3-CNV-VALUE<br />

* Specifying repetitive conversion data in the Web page <strong>for</strong><br />

* processing result output (prototype file)<br />

CALL “COBW3_SET_REPEAT” USING COBW3<br />

* Specifying the age<br />

MOVE “GET-AGE” TO COBW3-CNV-NAME<br />

MOVE Age TO COBW3-CNV-VALUE<br />

* Specifying repetitive conversion data in the Web page <strong>for</strong><br />

* processing result output (prototype file)<br />

CALL “COBW3_SET_REPEAT” USING COBW3<br />

:<br />

END-PERFORM.<br />

:<br />

* Specifying the company name<br />

MOVE “GET-OFFICE” TO COBW3-CNV-NAME.<br />

MOVE “FUJITSU” TO COBW3-CNV-VALUE.<br />

* Specifying conversion data to be repeated in the Web page <strong>for</strong><br />

* processing result output (prototype file)<br />

CALL “COBW3_SET_CNV” USING COBW3.<br />

:<br />

* Specifying the file name of the Web page <strong>for</strong> processing result<br />

* output (prototype file)<br />

MOVE “b.htm” TO COBW3-HTML-FILENAME.<br />

* Outputting the Web page <strong>for</strong> processing result output (prototype<br />

* file)<br />

CALL “COBW3_PUT_HTML” USING COBW3.<br />

:<br />

[Output result to the WWW browser]<br />

:<br />

Name Age Company<br />

SUZUKI 35 FUJITSU<br />

SATO 26 FUJITSU<br />

TANAKA 23 FUJITSU<br />

:


34 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

COBW3_SET_CNV, COBW3_SET_CNV_XX,<br />

COBW3_SET_CNV_NX, COBW3_SET_CNV_XN, and<br />

COBW3_SET_CNV_NN<br />

Each of these subroutines registers a conversion character string corresponding to a<br />

conversion name enclosed in "//COBOL//" specified in the Web page <strong>for</strong> processing<br />

result output (prototype file to be output by the COBW3_PUT_HTML subroutine. The<br />

appropriate subroutine must be called <strong>for</strong> each conversion name in the prototype file.<br />

Registered in<strong>for</strong>mation is referenced when COBW3_PUT_HTML is executed, and data<br />

in the Web page <strong>for</strong> processing result output (prototype file) is converted according<br />

to the registered conversion data.<br />

These subroutines have the following meanings.<br />

ASCII environment:<br />

• COBW3_SET_CNV<br />

Registers a conversion character string corresponding to the conversion name of<br />

an alphanumeric character string as an alphanumeric character string.<br />

Unicode environment:<br />

• COBW3_SET_CNV_XX<br />

Registers a conversion character string corresponding to the conversion nameof<br />

an alphanumeric character string as an alphanumeric character string.<br />

• COBW3_SET_CNV_NX<br />

Registers a conversion character string corresponding to the conversion name of<br />

a national character string as an alphanumeric character string.<br />

• COBW3_SET_CNV_XN<br />

Registers a conversion character string corresponding to the conversion name of<br />

an alphanumeric character string as a national character string.<br />

• COBW3_SET_CNV_NN<br />

Registers a conversion character string corresponding to the conversion name of<br />

a national character string as a national character string.<br />

Format:<br />

CALL "COBW3_SET_CNV" USING COBW3.<br />

CALL "COBW3_SET_CNV_XX" USING COBW3.<br />

CALL "COBW3_SET_CNV_NX" USING COBW3.<br />

CALL "COBW3_SET_CNV_XN" USING COBW3.


CALL "COBW3_SET_CNV_NN" USING COBW3.<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 35<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-CNV-NAME and COBW3-CNV-NAME-N<br />

Set a conversion name used <strong>for</strong> conversion.<br />

Set it in COBW3-CNV-NAME when COBW3_SET_CNV, COBW3_SET_CNV_XX or<br />

COBW3_SET_CNV_XN is used.<br />

Set a conversion name in COBW3-CNV-NAME-N when COBW3_SET_CNV_NX or<br />

COBW3_SET_CNV_NN is used.<br />

• COBW3-CNV-NAME-LENGTH [Optional]<br />

Set the character length of a conversion name with a valid space at the end to<br />

the number of bytes including the space.<br />

•<br />

•<br />

Value Meaning<br />

0 The length to the last character, excluding the space, is checked. However,<br />

the character length is regarded as 0 if COBW3-CNV-NAME or COBW3-CNV-<br />

NAME-N is filled with spaces only.<br />

1 to 30 Character strings of the specified character length are searched <strong>for</strong>.<br />

COBW3-CNV-VALUE and COBW3-CNV-VALUE-N<br />

Set the conversion result (conversion character string).<br />

Set it in COBW3-CNV-VALUE when COBW3_SET_CNV, COBW3_SET_CNV_XX or<br />

COBW3_SET_CNV_NX is used.<br />

Set it in COBW3-CNV-VALUE-N when COBW3_SET_CNV_XN or<br />

COBW3_SET_CNV_NN is used.<br />

COBW3-CNV-VALUE-LENGTH [Optional]<br />

Set the character length of a conversion character string with a valid space at the<br />

end in the number of bytes including the space.<br />

Value Meaning<br />

0 The length to the last character, excluding the space, is registered. However,<br />

the character length is regarded as 0 if COBW3-CNV-VALUE or COBW3-CNV-<br />

VALUE-N is filled with spaces only.<br />

1 to 1024 Character strings of the specified character length are searched <strong>for</strong>.


36 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

• COBW3-CNV-MODE [Optional]<br />

Set a conversion type.<br />

Condition-name Value Meaning<br />

COBW3-CNV-MODE<br />

–ADDREP<br />

COBW3-CNV-MODE<br />

–REPLACE<br />

COBW3-CNV-MODE<br />

–ADD<br />

LOW-VALUE The conversion data is added if the specified<br />

conversion name is not registered.<br />

“1” Data is converted. If the specified conversion<br />

name is not registered, an error is output and<br />

data is not converted.<br />

“2” The conversion data is added. If the specified<br />

conversion name is registered, an error is<br />

output and data is not added.<br />

• COBW3_SANITIZE_CNV [Optional]<br />

If characters that are vulnerable to a cross site scripting attack are found in<br />

conversion data, those characters are automatically replaced. This process is referred<br />

to as “sanitizing”.<br />

For more details on cross site scripting, refer to Appendix P, Security, in the<br />

<strong>NetCOBOL</strong> User’s <strong>Guide</strong>.<br />

COBW3_SANITIZE_CNV is valid when either COBW3_SET_CNV_XX or<br />

COBW3_SET_CNV_NX is used. However, if the code set is Unicode,<br />

COBW3_SANITIZE_CNV is also valid when COBW3_SET_CNV_XN or<br />

COBW3_SET_CNV_NN is used.<br />

Condition name Value Explanation<br />

COBW3-SANITIZE-CNV-OFF LOW-VALUE Does not sanitize.<br />

COBW3-SANITIZE-CNV-ON "1" Sanitize.<br />

NOTE:<br />

The sanitization procedure replaces the five characters that are vulnerable to a cross<br />

site scripting attack (&, , “, ‘) with the following escape characters:<br />

& → &amp;<br />

< → &lt;<br />

> → &gt;<br />

" → &quot;<br />

' → &#39;<br />

As a result, a single character is being replaced with 4-6 characters, increasing the<br />

length of the sanitized data. This means that, depending on the content of the<br />

unsanitized data, sanitizing data may cause the maximum data length (1024 bytes)<br />

set in the Web parameter VALUE to be exceeded. If this happens, the sanitized data<br />

is truncated automatically at 1024 bytes.<br />

It is also possible that the escape characters themselves may be truncated. In this<br />

case, the vulnerable character is deleted, not replaced. An example is given below.


Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 37<br />

Example: The unsanitized data area is 1021 bytes long. The first 1020 bytes<br />

contain n characters that do not require sanitizing, but the last character is an<br />

ampersand ( & ).<br />

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&


38 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Format:<br />

CALL "COBW3_DEL_CNV" USING COBW3.<br />

CALL "COBW3_DEL_CNV_X" USING COBW3.<br />

CALL "COBW3_DEL_CNV_N" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-CNV-NAME and COBW3-CNV-NAME-N<br />

Set a conversion name to be deleted.<br />

Set it in COBW3-CNV-NAME when COBW3_DEL_CNV or COBW3_DEL_CNV_X is<br />

used.<br />

Set it in COBW3-CNV-NAME-N when COBW3_DEL_CNV_N is used.<br />

•<br />

COBW3-CNV-NAME-LENGTH [Optional]<br />

Set the character length of a conversion name with a valid space at the end to<br />

the number of bytes including the space.<br />

Value Meaning<br />

0 The length to the last character, excluding the space, is checked. However, the<br />

character length is regarded as 0 if COBW3-CNV-NAME or COBW3-CNV-NAME-N<br />

is filled with spaces only.<br />

1 to 30 Character strings of the specified character length are searched <strong>for</strong>.<br />

Processing Result Data:<br />

None<br />

COBW3_INIT_CNV<br />

This subroutine initializes all conversion data specified using COBW3_SET_CNV_XX or<br />

other subroutines.<br />

Format:<br />

CALL "COBW3_INIT_CNV" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

None<br />

Processing Result Data:<br />

None


Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 39<br />

COBW3_SET_REPEAT, COBW3_SET_REPEAT_XX,<br />

COBW3_SET_REPEAT_NX, COBW3_SET_REPEAT_XN, and<br />

COBW3_SET_REPEAT_NN<br />

Each of these subroutines registers the repetitive conversion data of a conversion<br />

name enclosed in "//COBOL_REPEAT//" specified in a Web page <strong>for</strong> processing result<br />

output (prototype file) to be output by the "COBW3_PUT_HTML" subroutine.<br />

Registered in<strong>for</strong>mation is referenced when COBW3_PUT_HTML is executed. The<br />

conversion name specified in the repetition range in the Web page <strong>for</strong> processing<br />

result output (prototype file) is converted according to the number of repetitive<br />

conversion character strings registered <strong>for</strong> the same conversion name.<br />

Each subroutine has the following meaning:<br />

ASCII environment:<br />

• COBW3_SET_REPEAT<br />

Registers the conversion character string corresponding to an alphanumeric<br />

character string conversion name as an alphanumeric character string.<br />

Unicode environment:<br />

• COBW3_SET_REPEAT_XX<br />

Registers the conversion character string corresponding to an alphanumeric<br />

character string conversion name as an alphanumeric character string.<br />

•<br />

•<br />

COBW3_SET_REPEAT_NX<br />

Registers the conversion character string corresponding to a national character<br />

string conversion name as an alphanumeric character string.<br />

COBW3_SET_REPEAT_XN<br />

Registers the conversion character string corresponding to an alphanumeric<br />

character string conversion name as a national character string.<br />

• COBW3_SET_REPEAT_NN<br />

Registers the conversion character string corresponding to a national character<br />

string conversion name as a national character string.<br />

Note: Register a repetitive conversion character string <strong>for</strong> each conversion name by<br />

calling "COBW3_SET_REPEAT_XX" or other subroutines.<br />

The conversion character strings are converted in repetitive conversion in the order<br />

of registration using "COBW3_SET_REPEAT_XX" or other subroutines.<br />

Specify the same number repetitive conversion character strings as conversion<br />

names in the same repetition range.<br />

Format:<br />

CALL "COBW3_SET_REPEAT" USING COBW3.<br />

CALL "COBW3_SET_REPEAT_XX" USING COBW3.


40 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

CALL "COBW3_SET_REPEAT_NX" USING COBW3.<br />

CALL "COBW3_SET_REPEAT_XN" USING COBW3.<br />

CALL "COBW3_SET_REPEAT_NN" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-CNV-NAME and COBW3-CNV-NAME-N<br />

Set a conversion name used <strong>for</strong> conversion.<br />

Set it in COBW3-CNV-NAME when COBW3_SET_REPEAT,<br />

COBW3_SET_REPEAT_XX or COBW3_SET_REPEAT_XN is used.<br />

•<br />

•<br />

•<br />

Set it in COBW3-CNV-NAME-N when COBW3_SET_REPEAT_NX or<br />

COBW3_SET_REPEAT_NN is used.<br />

COBW3-CNV-NAME-LENGTH [Optional]<br />

Set the character length of a conversion name with a valid space at the end to<br />

the number of bytes including the space.<br />

Value Meaning<br />

0 The length up to the last character, excluding the space, is checked. However,<br />

the character length is regarded as 0 if COBW3-CNV-NAME or COBW3-CNV-<br />

NAME-N is filled with spaces only.<br />

1 to 30 Character strings of the specified character length are searched <strong>for</strong><br />

COBW3-CNV-VALUE and COBW3-CNV-VALUE-N<br />

Set a conversion result (conversion character string).<br />

Set it in COBW3-CNV-VALUE when COBW3_SET_REPEAT,<br />

COBW3_SET_REPEAT_XX or COBW3_SET_REPEAT_NX is used.<br />

Set it in COBW3-CNV-VALUE-N when COBW3_SET_REPEAT_XN or<br />

COBW3_SET_REPEAT_NN is used.<br />

COBW3-CNV-VALUE-LENGTH [Optional]<br />

Set the character length of a conversion character string with a valid space at the<br />

end to the number of bytes including the space.<br />

Value Meaning<br />

0 The length to the last character, excluding the space, is registered. However,<br />

the character length is regarded as 0 if COBW3-CNV-VALUE or COBW3-CNV-<br />

VALUE-N is filled with spaces only.<br />

1 to 1024 Character strings of the specified character length are searched <strong>for</strong>.<br />

Specify a space as the conversion character string, 0 as the conversion character<br />

string, and register the repetitive conversion data, if it is necessary to specify a space<br />

as the conversion result.


• COBW3_SANITIZE_CNV [Optional]<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 41<br />

If characters that are vulnerable to a cross site scripting attack are found in<br />

conversion data, those characters are automatically replaced. This process is referred<br />

to as “sanitizing”.<br />

For more details on cross site scripting, refer to Appendix P, Security, in the<br />

<strong>NetCOBOL</strong> User’s <strong>Guide</strong>.<br />

COBW3_SANITIZE_CNV is valid when either COBW3_SET_REPEAT_XX or<br />

COBW3_SET_ REPEAT_NX is used. However, if the code set is Unicode,<br />

COBW3_SANITIZE_CNV is also valid when COBW3_SET_ REPEAT_XN or<br />

COBW3_SET_ REPEAT_NN is used.<br />

Condition name Value Explanation<br />

COBW3-SANITIZE-CNV-OFF LOW-VALUE Does not sanitize.<br />

COBW3-SANITIZE-CNV-ON "1" Sanitize.<br />

NOTE:<br />

The sanitization procedure replaces the five characters that are vulnerable to a cross<br />

site scripting attack (&, , “, ‘) with the following escape characters:<br />

& → &amp;<br />

< → &lt;<br />

> → &gt;<br />

" → &quot;<br />

' → &#39;<br />

As a result, a single character is being replaced with 4-6 characters, increasing the<br />

length of the sanitized data. This means that, depending on the content of the<br />

unsanitized data, sanitizing data may cause the maximum data length (1024 bytes)<br />

set in the Web parameter VALUE to be exceeded. If this happens, the sanitized data<br />

is truncated automatically at 1024 bytes.<br />

It is also possible that the escape characters themselves may be truncated. In this<br />

case, the vulnerable character is deleted, not replaced. An example is given below.<br />

Example: The unsanitized data area is 1021 bytes long. The first 1020 bytes<br />

contain n characters that do not require sanitizing, but the last character is an<br />

ampersand ( & ).<br />

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&


42 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

This exceeds the 1024-byte limit, but truncating the data to 1024 bytes would<br />

interrupt the escape character string (&amp;). For this reason, the ampersand is<br />

deleted instead of being replaced.<br />

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


Format:<br />

CALL "COBW3_DEL_REPEAT" USING COBW3.<br />

CALL "COBW3_DEL_REPEAT_X" USING COBW3.<br />

CALL "COBW3_DEL_REPEAT_N" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-CNV-NAME and COBW3-CNV-NAME-N<br />

Set a conversion name to be deleted.<br />

Set it in COBW3-CNV-NAME when COBW3_DEL_REPEAT or<br />

COBW3_DEL_REPEAT_X is used.<br />

•<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 43<br />

Set it in COBW3-CNV-NAME-N when COBW3_DEL_REPEAT_N is used.<br />

COBW3-CNV-NAME-LENGTH [Optional]<br />

Set the character length of a conversion character string with a valid space at the<br />

end to the number of bytes including the space.<br />

Value Meaning<br />

0 The length to the last character, excluding the space, is checked. However,<br />

the character length is regarded as 0 if COBW3-CNV-NAME or COBW3-CNV-<br />

NAME-N is filled with spaces only.<br />

1 to 30 Character strings of the specified character length are searched <strong>for</strong>.<br />

Processing Result Data:<br />

None


44 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

COBW3_INIT_REPEAT<br />

This subroutine initializes all repetitive conversion data specified using<br />

COBW3_SET_REPEAT_XX or other subroutine.<br />

Format:<br />

CALL "COBW3_INIT_REPEAT" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

None<br />

Processing Result Data:<br />

None<br />

COBW3_PUT_TEXT<br />

This subroutine outputs a specified character string and a line feed character to the<br />

WWW browser.<br />

Format:<br />

CALL "COBW3_PUT_TEXT" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-PUT-STRING<br />

Set a character string to be output.<br />

• COBW3-PUT-STRING-LENGTH [Optional]<br />

Set the character length of a character string with a valid space at the end to the<br />

number of bytes including the space.<br />

Value Meaning<br />

0 Character strings of any length, excluding the space, are output.<br />

However, the character length is regarded as 0 (i.e., line feed<br />

character only) if COBW3-PUT-STRING is filled with spaces only.<br />

1 to 1024 Character strings of the specified character length are output.<br />

Processing Result Data:<br />

None<br />

Outputting Character String Data (including a line feed character) to the<br />

WWW Browser:<br />

The following example shows how to output " Thank you <strong>for</strong> your<br />

cooperation. " to the WWW browser.


Application example:<br />

[COBOL program]<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 45<br />

:<br />

00036 * Setting the character string to be output<br />

00037 MOVE “ Thank you <strong>for</strong> your cooperation.”<br />

00038 TO COBW3-PUT-STRING.<br />

00039 * Outputting the character string data<br />

00040 CALL “COBW3_PUT_TEXT” USING COBW3.<br />

:<br />

[Output result on the WWW browser]<br />

:<br />

Thank you <strong>for</strong> your cooperation.<br />

:<br />

Execute System Commands<br />

COBW3_SYSTEM<br />

This subroutine executes a system command from the Web application.<br />

Format:<br />

CALL "COBW3_SYSTEM" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-SYSTEMINFO<br />

Set a system command to be executed and its parameters.<br />

Processing Result Data:<br />

None<br />

Note: Due to the extreme risk to the integrity of the operating system, we<br />

recommend that you never create a web application that permits execution of a<br />

command string input to the browser.<br />

Free <strong>SAF</strong> Execution Environment Resources<br />

COBW3_ FREE<br />

This subroutine frees resources obtained by a <strong>SAF</strong> subroutine. To prevent<br />

exhaustion of system resources, call this subroutine at the end of every connection<br />

of the Web application.<br />

Format:<br />

CALL "COBW3_FREE" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

None


46 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Processing Result Data:<br />

None<br />

Get Request In<strong>for</strong>mation<br />

COBW3_RECEIVE_HEADER<br />

This subroutine acquires the HTTP header of a request.<br />

Format:<br />

CALL "COBW3_RECEIVE_HEADER" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-HEADER-NAME<br />

•<br />

Set a header name to be acquired.<br />

COBW3-HEADER-NAME-LENGTH [Optional]<br />

Set the character length of a header name with a valid space at the end to the<br />

number of bytes including the space.<br />

Value Meaning<br />

0 The length to the last character, excluding the space, is checked.<br />

1 to 64 Header names of the specified character length are searched <strong>for</strong>.<br />

Note: Specify 0 since header names normally have no spaces at the end.<br />

Processing Result Data:<br />

•<br />

•<br />

COBW3-HEADER-VALUE<br />

The header value corresponding to the requested header name is set.<br />

COBW3-HEADER-VALUE-LENGTH<br />

The character length (byte length) of the header value corresponding to the<br />

requested header name is set.<br />

COBW3_GET_REQUEST_INFO<br />

This subroutine acquires in<strong>for</strong>mation concerning a request.<br />

CALL "COBW3_GET_REQUEST_INFO" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-REQUEST-INFO-TYPE<br />

Specify the in<strong>for</strong>mation to be acquired:


Condition-name Value Meaning<br />

COBW3-URI LOW-VALUE Request URI<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 47<br />

COBW3-URL “1” Request URL<br />

COBW3-SERVER-TYPE<br />

(COBW3-LISTENERTYPE)<br />

“2” Server type<br />

COBW3-VIRTUALPATH “3” Virtual path name of a request<br />

COBW3-PHYSICALPATH “4” Physical path name corresponding to the<br />

virtual path of a request<br />

COBW3-QUERYSTRING “5” Web parameter<br />

COBW3-LANGUAGE “6” List of languages which the WWW browser<br />

can receive<br />

COBW3-ENCODING “7” List of encoding which the WWW browser<br />

can receive<br />

COBW3-REQMIMETYPE “8” MIME type of a request<br />

COBW3-REQUEST-<br />

METHOD<br />

“9” Request method<br />

COBW3-PATH-INFO “A” Extended path name sent by the WWW<br />

browser<br />

COBW3-PATH-<br />

TRANSLATED<br />

“B” Physical path name corresponding to the<br />

extended path<br />

COBW3-REMOTE-ADDR “C” IP address of the client<br />

COBW3-REMOTE-HOST “D” Host name of the client<br />

COBW3-GATEWAY<br />

–INTERFACE<br />

“E” Revision of the support CGI<br />

COBW3-SERVER-NAME “F” Host name of the server<br />

COBW3-SERVER-PORT “G” Connection port No. of the server<br />

COBW3-SERVER<br />

–PROTOCOL<br />

“H” Protocol used by the server<br />

COBW3-SERVER-PORT “I” "1" is returned during secure<br />

–SECURE<br />

communication. "0" is returned otherwise.<br />

Note: No server type may be acquired.<br />

If the extended path is specified, it may be impossible to acquire correct request<br />

URI, request URL, MIME type of the request, virtual path name of the request, and<br />

physical path name corresponding to the virtual path of a request.<br />

Processing Result Data:<br />

• COBW3-REQUEST-INFO<br />

Acquired request in<strong>for</strong>mation is set.<br />

• COBW3-REQUEST-INFO-LENGTH<br />

The character length (byte length) of the acquired request in<strong>for</strong>mation is set.


48 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

COBW3_GET_AUTHORIZE<br />

This subroutine acquires authorization in<strong>for</strong>mation from the WWW browser. The<br />

authorization in<strong>for</strong>mation includes the ID and password of the user and the IP<br />

address of the client.<br />

Format:<br />

CALL "COBW3_GET_AUTHORIZE" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

None<br />

Processing Result Data:<br />

•<br />

•<br />

•<br />

•<br />

•<br />

•<br />

COBW3-USERID<br />

The acquired user ID is set.<br />

COBW3-USERID-LENGTH<br />

The character length (byte length) of the user ID is set.<br />

COBW3-PASSWORD<br />

The acquired user password is set.<br />

COBW3-PASSWORD-LENGTH<br />

The character length (byte length) of the user password is set.<br />

COBW3-IP-ADDRESS<br />

The acquired client IP address is set.<br />

COBW3-IP-ADDRESS-LENGTH<br />

The character length (byte length) of the IP address is set.<br />

• COBW3-AUTH-TYPE<br />

The acquired authorization type is set.<br />

• COBW3-AUTH-TYPE-LENGTH<br />

The character length (byte length) of the authorization type is set.<br />

Note: This subroutine cannot acquire any in<strong>for</strong>mation of an anonymous<br />

authorization except the IP address.<br />

It may acquire any type of in<strong>for</strong>mation of a basic authorization. "basic" is set as the<br />

authorization type.


Manipulate Cookie Data<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 49<br />

COBW3_SET_COOKIE, COBW3_SET_COOKIE_XX,<br />

COBW3_SET_COOKIE_NX, COBW3_SET_COOKIE_XN,<br />

COBW3_SET_COOKIE_NN<br />

Register the Cookie data to be sent to the WWW browser. The registered Cookie<br />

data is used <strong>for</strong> header output.<br />

Each subroutine has the following meaning.<br />

ASCII environment:<br />

• COBW3_SET_COOKIE<br />

Registers the alphanumeric Cookie name and the corresponding Cookie value as<br />

an alphanumeric character string.<br />

Unicode environment:<br />

• COBW3_SET_COOKIE_XX<br />

Registers the alphanumeric Cookie name and the corresponding Cookie value as<br />

an alphanumeric character string.<br />

•<br />

•<br />

•<br />

COBW3_SET_COOKIE_NX<br />

Registers the national character Cookie name and the corresponding Cookie<br />

value as an alphanumeric character string.<br />

COBW3_SET_COOKIE_XN<br />

Registers the alphanumeric Cookie name and the corresponding Cookie value as<br />

a national character string.<br />

COBW3_SET_COOKIE_NN<br />

Registers the national character Cookie name and the corresponding Cookie<br />

value as a national character string.<br />

Note: Use this subroutine be<strong>for</strong>e calling COBW3_PUT_HTML or COBW3_PUT_TEXT.<br />

The Cookie character code sent to the WWW browser is always ASCII regardless of<br />

the COBOL operation code system.<br />

Formats:<br />

CALL "COBW3_SET_COOKIE" USING COBW3.<br />

CALL "COBW3_SET_COOKIE_XX" USING COBW3.<br />

CALL "COBW3_SET_COOKIE_NX" USING COBW3.<br />

CALL "COBW3_SET_COOKIE_XN" USING COBW3.


50 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

CALL "COBW3_SET_COOKIE_NN" USING COBW3.<br />

Data setup during call:<br />

• COBW3-COOKIE-NAME, COBW3-COOKIE-NAME-N<br />

Sets a Cookie name you wish to register.<br />

Specify “COBW3-COOKIE-NAME” <strong>for</strong> the COBW3_SET_COOKIE,<br />

COBW3_SET_COOKIE_XX or COBW3_SET_COOKIE_XN. Specify “COBW3-<br />

COOKIE-NAME-N” <strong>for</strong> the COBW3_SET_COOKIE_NX or<br />

COBW3_SET_COOKIE_NN.<br />

• COBW3-COOKIE-NAME-LENGTH [Optional]<br />

Sets the length of Cookie name character string (in bytes) including spaces if the<br />

Cookie name has a valid space at the end .<br />

•<br />

•<br />

Value Meaning<br />

0 Registers the Cookie name consisting of a character string including the last<br />

character except <strong>for</strong> a space. However, if the COBW3_COOKIE-NAME or<br />

COBW3_COOKIE-NAME-N consists of only spaces, the length of character string<br />

is considered to be zero (0).<br />

1 to 64 Register the Cookie name consisting of the specified number of characters.<br />

COBW3-COOKIE-VALUE, COBW3-COOKIE-VALUE-N<br />

Set a Cookie value.<br />

Specify “COBW3-COOKIE-VALUE” <strong>for</strong> COBW3_SET_COOKIE,<br />

COBW3_SET_COOKIE_XX or <strong>for</strong> COBW3_SET_COOKIE_NX.<br />

Also, set “COBW3-COOKIE-VALUE-N” <strong>for</strong> COBW3_SET_COOKIE_XN or<br />

COBW3_SET_COOKIE_NN.<br />

COBW3-COOKIE-VALUE-LENGTH [Optional]<br />

Sets the length of the Cookie value character string (in bytes) including spaces if<br />

a Cookie value having a valid space at its end is specified.<br />

Value Meaning<br />

0 Registers a Cookie value consisting of a character string including the last<br />

character except <strong>for</strong> a space. However, if the COBW3-COOKIE-VALUE or<br />

COBW3-COOKIE-VALUE-N contains of only spaces, the length of character<br />

string is considered to be zero (0).<br />

1 to 1024 Register a Cookie value consisting of the specified number of characters.<br />

• COBW3-COOKIE-EXPIRES [Optional]<br />

Use this subroutine to specify the Cookie expiration date. The expiration time<br />

must be set in Greenwich Mean Time (GMT).<br />

- COBW3-COOKIE-EXPIRES-YEAR (Year) (1582 to 9999)<br />

- COBW3-COOKIE-EXPIRES-MONTH (Month) (01 to 12)<br />

- COBW3-COOKIE-EXPIRES-DAY (Day) (01 to 31; with the last day depending<br />

on the month)


- COBW3-COOKIE-EXPIRES-HOUR (Hours) (00 to 23)<br />

- COBW3-COOKIE-EXPIRES-MIN (Minutes) (00 to 59)<br />

- COBW3-COOKIE-EXPIRES-SEC (Seconds) (00 to 59)<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 51<br />

Note: If the expiration date is omitted, the Cookie data is deleted when the browser<br />

is terminated. The Cookie data that the browser currently has is deleted immediately<br />

if a clock time is specified that is already past.<br />

Specify an expiration date after October 15th of 1582. If you specify an earlier date<br />

, the expiration date is will not be correctly set, due to failure of the automatic day of<br />

week calculation.<br />

•<br />

•<br />

•<br />

COBW3-COOKIE-DOMAIN [Optional]<br />

Sets a domain where the Cookie is valid.<br />

COBW3-COOKIE-PATH [Optional]<br />

Sets a virtual path where the Cookie is valid.<br />

COBW3-COOKIE-SECURE [Optional]<br />

Sets the security. If the security is on, the Cookie data is sent from the WWW<br />

browser only when SSL is used.<br />

Condition-name Value Meaning<br />

COBW3-COOKIE<br />

-SECURE-OFF<br />

LOW-VALUE Allow any method to transport the cookie<br />

COBW3-COOKIE<br />

-SECURE-ON<br />

“1” Allow only SSL to transport the cookie<br />

• COBW3-COOKIEMODE [Optional]<br />

Sets a registration type of Cookie data.<br />

Condition-name Value Meaning<br />

COBW3-COOKIE<br />

–MODE-ADDREP<br />

COBW3-COOKIE<br />

–MODE-REPLACE<br />

COBW3-COOKIE<br />

–MODE-ADD<br />

Process Result Data:<br />

None<br />

LOW-VALUE Adds Cookie data if the specified Cookie name is<br />

not registered.<br />

“1” Replaces the Cookie data. If the specified Cookie<br />

name is not registered, an error is output and the<br />

name is not registered.<br />

“2” Adds Cookie data. If the specified Cookie name is<br />

already registered, an error is output and the data<br />

is not added.


52 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

COBW3_DEL_COOKIE, COBW3_DEL_COOKIE_X,<br />

COBW3_DEL_COOKIE_ N<br />

Delete Cookie data which has been registered by COBW3_SET_COOKIE_XX or<br />

others.<br />

Each subroutine has the following meaning.<br />

ASCII environment:<br />

• COBW3_DEL_COOKIE<br />

Deletes the Cookie data corresponding to the alphanumeric Cookie name.<br />

Unicode environment:<br />

• COBW3_DEL_COOKIE_X<br />

Deletes the Cookie data corresponding to the alphanumeric Cookie name.<br />

• COBW3_DEL_COOKIE_N<br />

Deletes the Cookie data corresponding to the national character Cookie name.<br />

Note: Use this subroutine be<strong>for</strong>e calling COBW3_PUT_HTML or COBW3_PUT_TEXT.<br />

Formats:<br />

CALL "COBW3_DEL_COOKIE" USING COBW3.<br />

CALL "COBW3_DEL_COOKIE_X" USING COBW3.<br />

CALL "COBW3_DEL_COOKIE_N" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-COOKIE-NAME, COBW3-COOKIE-NAME-N<br />

Sets a Cookie name to be deleted.<br />

Specify “COBW3-COOKIE-NAME” <strong>for</strong> the COBW3_DEL_COOKIE or<br />

COBW3_DEL_COOKIE_X.<br />

•<br />

Also, specify “COBW3-COOKIE-NAME-N” <strong>for</strong> the COBW3_DEL_COOKIE_N.<br />

COBW3-COOKIE-NAME-LENGTH [Optional]<br />

Sets the length of Cookie name character string (in bytes) containing spaces if a<br />

Cookie name having a valid space at its end is specified.<br />

Value Meaning<br />

0 Deletes up to the end of character string except <strong>for</strong> a space. However, if the<br />

COBW3-COOKIE-NAME or COBW3-COOKIE-NAME-N consists of only spaces, the<br />

length of character string is considered to be zero (0).<br />

1 to 64 Deletes the specified length of character string.


Process result data:<br />

None<br />

COBW3_INIT_COOKIE<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 53<br />

Initializes the Cookie data that has been registered by the COBW3_SET_COOKIE_XX<br />

or others.<br />

Note: Use this subroutine be<strong>for</strong>e calling COBW3_PUT_HTML or COBW3_PUT_TEXT.<br />

Format:<br />

CALL "COBW3_INIT_COOKIE" USING COBW3.<br />

Data setup during call:<br />

• COBW3-COOKIE-INIT-MODE [Optional]<br />

Sets an initialization type of Cookie data.<br />

Condition-name Value Meaning<br />

COBW3-COOKIE<br />

–INIT-MODE-NORMAL<br />

LOW-VALUE Initializes all Cookie data.<br />

COBW3-COOKIE<br />

“1” Initializes the requested Cookie data to the<br />

–INIT-MODE-REQUEST<br />

initial value.<br />

Process result data:<br />

None<br />

COBW3_GET_COOKIE, COBW3_GET_COOKIE_XX,<br />

COBW3_GET_COOKIE_NX, COBW3_GET_COOKIE_XN,<br />

COBW3_GET_COOKIE_NN<br />

Search any Cookie name in the requested Cookie data collected by the<br />

“COBW3_INIT.” Each subroutine has the following meaning.<br />

ASCII environment:<br />

• COBW3_GET_COOKIE<br />

Searches <strong>for</strong> a Cookie name consisting of an alphanumeric character string, and<br />

returns the corresponding Cookie value in an alphanumeric character string.<br />

Unicode environment:<br />

• COBW3_GET_COOKIE_XX<br />

Searches a Cookie name consisting of an alphanumeric character string, and<br />

returns the corresponding Cookie value in an alphanumeric character string.<br />

• COBW3_GET_COOKIE_NX<br />

Searches a Cookie name consisting of a national character string, and returns the<br />

corresponding Cookie value in an alphanumeric character string.


54 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

•<br />

•<br />

COBW3_GET_COOKIE_XN<br />

Searches a Cookie name consisting of an alphanumeric character string, and<br />

returns the corresponding Cookie value in a national character string.<br />

COBW3_GET_COOKIE_NN<br />

Searches a Cookie name consisting of a national character string, and returns the<br />

corresponding Cookie value in a national character string.<br />

When the collected Cookie value is stored, it is padded with blanks.<br />

Format:<br />

CALL "COBW3_GET_COOKIE" USING COBW3.<br />

CALL "COBW3_GET_COOKIE_XX" USING COBW3.<br />

CALL "COBW3_GET_COOKIE_NX" USING COBW3.<br />

CALL "COBW3_GET_COOKIE_XN" USING COBW3.<br />

CALL "COBW3_GET_COOKIE_NN" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-COOKIE-NAME, COBW3-COOKIE-NAME-N<br />

Sets a Cookie name to be searched.<br />

Set a Cookie name in COBW3-COOKIE-NAME <strong>for</strong> COBW3_GET_COOKIE,<br />

COBW3_GET_COOKIE_XX or COBW3_GET_COOKIE_XN. Set a Cookie name in<br />

COBW3-COOKIE-NAME-N <strong>for</strong> COBW3_GET_COOKIE_NX or<br />

COBW3_GET_COOKIE_NN.<br />

• COBW3-COOKIE-NAME-LENGTH [Optional]<br />

Sets the length of Cookie name character string (in bytes) containing spaces to<br />

search a Cookie name which ends with a valid space.<br />

Value Meaning<br />

0 Searches a Cookie name of the entire character string except <strong>for</strong> spaces.<br />

However, if the COBW3-COOKIE-NAME or COBW3-COOKIE-NAME-N consists of<br />

only spaces, the length of character string is considered to be zero.<br />

1 to 64 Searches a Cookie name in the specified length of character string.


Process Result Data:<br />

• COBW3-SEARCH-FLAG<br />

•<br />

•<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 55<br />

Condition-name Value Meaning<br />

COBW3-SEARCH-FLAG–NON “0” The specified name is not found.<br />

COBW3-SEARCH–FLAG-EXIST “1” The specified name has been found.<br />

COBW3-COOKIE-VALUE, COBW3-COOKIE-VALUE-N<br />

Set a Cookie value corresponding to the Cookie name to be searched.<br />

The Cookie value is set in COBW3-COOKIE-VALUE <strong>for</strong> COBW3_GET_COOKIE,<br />

COBW3_GET_COOKIE_XX or COBW3_GET_COOKIE_NX.<br />

It is set in COBW3-COOKIE-VALUE-N <strong>for</strong> COBW3_GET_COOKIE_XN or<br />

COBW3_GET_COOKIE_NN.<br />

COBW3-COOKIE-VALUE-LENGTH<br />

Sets the length of Cookie value character string (in bytes) corresponding to the<br />

Cookie name to be searched.<br />

Manipulate Uploaded Files<br />

COBW3_GET_UPLOADFILE_INFO,COBW3_GET_UPLOADFILE_<br />

INFO_X and COBW3_GET_UPLOADFILE_INFO_N<br />

These subroutines acquire the in<strong>for</strong>mation on an uploaded file. Details of these<br />

subroutines are as follows:<br />

ASCII environment<br />

• COBW3_GET_UPLOADFILE_INFO<br />

Retrieves the name of the uploaded file (alphanumeric character string specified<br />

in NAME), and acquires the in<strong>for</strong>mation about the found uploaded file.<br />

Unicode environment<br />

•<br />

•<br />

COBW3_GET_UPLOADFILE_INFO_X<br />

Retrieves the name of the uploaded file (alphanumeric character string specified<br />

in NAME), and acquires the in<strong>for</strong>mation about the found uploaded file.<br />

COBW3_GET_UPLOADFILE_INFO_N<br />

Retrieves the name of the uploaded file (national language character strings<br />

specified in NAME), and acquires the in<strong>for</strong>mation about the found uploaded file.<br />

Format:<br />

CALL "COBW3_GET_UPLOADFILE_INFO" USING COBW3.<br />

CALL "COBW3_GET_UPLOADFILE_INFO_X" USING COBW3.


56 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

CALL "COBW3_GET_UPLOADFILE_INFO_N" USING COBW3.<br />

Data setting <strong>for</strong> calling:<br />

• COBW3-SEARCH-DATA and COBW3-SEARCH-DATA-N<br />

Set the name (NAME) of the upload file to be retrieved (The name specified in<br />

“name” of the HTML document (Web page <strong>for</strong> invoking application) must be set<br />

instead of the file name).<br />

For COBW3_GET_UPLOADFILE_INFO and COBW3_GET_UPLOADFILE_INFO_X,<br />

set the name to COBW3-SEARCH-DATA.<br />

•<br />

For COBW3_GET_UPLOADFILE_INFO_N, set the name to COBW3-SEARCH-<br />

DATA-N.<br />

COBW3-SEARCH-LENGTH [optional]<br />

If the name (NAME) has a valid blank at the end, set the string length (byte<br />

length) of the name including the blank.<br />

Value Meaning<br />

0 Searches the upload file name using the length up to the last character<br />

excluding the blank. However, if COBW3-SEARCH-DATA or COBW3-SEARCH-<br />

DATA-N is completely blank, the string length is set to zero <strong>for</strong> processing.<br />

1 to 1024 Searches the upload file name using the specified string length.<br />

• COBW3-NUMBER [optional]<br />

If multiple entities with the same name (NAME) exist in Web parameters, set the<br />

order of appearance of names to be searched.<br />

Condition name Value Meaning<br />

COBW3-NUMBER-INIT 1 Searches the name that matches first.<br />

- - - - - - - - - - 2 to 9999 Searches the names in the specified order of<br />

appearance.<br />

Processing Result Data:<br />

• COBW3-SEARCH-FLAG<br />

•<br />

•<br />

Condition name Value Meaning<br />

COBW3-SEARCH-FLAG-NON "0" The name to be searched does not exist, or<br />

size of the uploaded file is 0.<br />

COBW3-SEARCH-FLAG-EXIST "1" The name to be searched exists.<br />

COBW3-UPLD-CL-FILE-PATH<br />

Sets the path name of the upload file in the client which corresponds to the<br />

retrieved name (NAME).<br />

COBW3-UPLD-CL-FILE-PATH-LENGTH<br />

Sets the character string length (byte length) of the path name of the upload file<br />

in the client which corresponds to the retrieved name (NAME).


•<br />

•<br />

•<br />

•<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 57<br />

COBW3-UPLD-CL-FILE-NAME<br />

Sets the file name of the upload file in the client which corresponds to the<br />

retrieved name (NAME).<br />

COBW3-UPLD-CL-FILE-NAME-LENGTH<br />

Sets the character string length (byte length) of the file name of the upload file<br />

in the client which corresponds to the retrieved name (NAME).<br />

COBW3-UPLD-CONTENT-TYPE<br />

Sets the character string that indicates the Content-type of the upload file that<br />

corresponds to the retrieved name (NAME).<br />

COBW3-UPLD-CONTENT-TYPE-LENGTH<br />

Sets the character string length (byte length) of the character string that<br />

indicates the content type of the upload file that corresponds to the retrieved<br />

name (NAME).<br />

• COBW3-UPLD-FILE-SIZE<br />

Sets the uploaded file size (byte length) .<br />

Note: When “\” is included in the uploaded file name when the client is UNIX, the<br />

file name and the path name cannot be correctly received.<br />

Example:<br />

[c.htm (Web page <strong>for</strong> invoking application)]<br />

:<br />

<br />

<br />

Your Name:<br />

Send file 1:<br />

<br />

<br />

<br />

:<br />

[COBOL source program]<br />

:<br />

* Name setup<br />

MOVE "FILE1" TO COBW3-SEARCH-DATA.<br />

* Acquisition of upload file in<strong>for</strong>mation<br />

CALL "COBW3_GET_UPLOADFILE_INFO_X" USING COBW3.<br />

:<br />

IF COBW3-SEARCH-FLAG-EXIST THEN<br />

* Setup of name of file to be generated<br />

MOVE "d.tmp" TO COBW3-UPLOADED-FILENAME<br />

* File generation<br />

CALL "COBW3_GEN_UPLOADFILE_X" USING COBW3<br />

:<br />

* File data processing<br />

:<br />

* Deletion of generated file<br />

CALL "COBW3_DEL_UPLOADEDFILE" USING COBW3<br />

END-IF.<br />

:


58 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

COBW3_GEN_UPLOADFILE, COBW3_GEN_UPLOADFILE_X and<br />

COBW3_GEN_UPLOADFILE_N<br />

These subroutines generate an uploaded file by using a specified file name. The<br />

details of these subroutines are as follows:<br />

ASCII environment<br />

• COBW3_GEN_UPLOADFILEX<br />

Searches the name (NAME) of an alphanumeric character string, and generates<br />

the found uploaded file by using the specified file name.<br />

Unicode environment<br />

• COBW3_GEN_UPLOADFILE_X<br />

Searches the name (NAME) of an alphanumeric character string, and generates<br />

the found uploaded file by using the specified file name.<br />

• COBW3_GEN_UPLOADFILE_N<br />

Searches the name (NAME) of a national character string, and generates the<br />

found uploaded file by using the specified file name.<br />

Note: Uploaded files must not be generated as executable files because of the<br />

threat to security. Especially, uploaded files must not be generated as files that can<br />

be automatically executed by the system.<br />

Format:<br />

CALL "COBW3_GEN_UPLOADFILE" USING COBW3.<br />

CALL " COBW3_GEN_UPLOADFILE_X" USING COBW3.<br />

CALL " COBW3_GEN_UPLOADFILE_N" USING COBW3.<br />

Data setting <strong>for</strong> calling:<br />

• COBW3-SEARCH-DATA and COBW3-SEARCH-DATA-N<br />

Set the name (NAME) of the uploaded file to be searched (The name specified<br />

in “name” of the HTML document [Web page <strong>for</strong> invoking application] must be<br />

set instead of the file name).<br />

For COBW3_GEN_UPLOADFILE and COBW3_GEN_UPLOADFILE_X, set the name<br />

to COBW3-SEARCH-DATA.<br />

For COBW3_GEN_UPLOADFILE_N, set the name to COBW3-SEARCH-DATA-N.<br />

• COBW3-SEARCH-LENGTH [optional]<br />

If the value (VALUE) has a valid blank at the end, set the string length (byte<br />

length) of the value including the blank.


Value Meaning<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 59<br />

0 Searches the name using the length up to the last character excluding the<br />

blank.<br />

1 to 1024 Searches the name using the specified string length.<br />

• COBW3-NUMBER [optional]<br />

Sets the order of appearance of NAMES to be searched when there are multiple<br />

NAMES with the same name in the Web parameters.<br />

Condition name Value Meaning<br />

COBW3-NUMBER-INIT 1 Searches the name that matches first.<br />

- - - - - - - - - - 2 to Searches the name in the specified order of<br />

9999 appearance.<br />

• COBW3-UPLOADED-FILENAME<br />

Specify the name of the file to be generated on the server.<br />

Processing Result Data:<br />

• COBW3-SEARCH-FLAG<br />

Condition name Value Meaning<br />

COBW3-SEARCH-FLAG-NON "0" The name to be searched does not exist.<br />

COBW3-SEARCH-FLAG-EXIST "1" The name to be searched exists.<br />

COBW3_DEL_UPLOADFILE<br />

This subroutine deletes an uploaded file that was generated using a subroutine such<br />

as COBW3_GEN_UPLOADFILE.<br />

This subroutine can delete a file that was generated using<br />

COBW3_GEN_UPLOADFILE, COBW3_GEN_UPLOADFILE_X or<br />

COBW3_GEN_UPLOADFILE_N within the same request. File generation or deletion<br />

among two or more requests (two or more pages) cannot be per<strong>for</strong>med.<br />

Format:<br />

CALL "COBW3_DEL_UPLOADFILE" USING COBW3.<br />

Data setting <strong>for</strong> calling:<br />

• COBW3-UPLOADED-FILENAME<br />

Set the name of the file to be deleted.<br />

Processing Result Data:<br />

None


60 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Manage Sessions<br />

COBW3_START_SESSION<br />

Starts a session. Also, it sets a data type and timeout value <strong>for</strong> the session.<br />

Notes: Call this subroutine be<strong>for</strong>e using the “COBW3_PUT_TEXT,”<br />

“COBW3_PUT_HTML” or “COBW3_FREE.” Once any of these subroutines is used, no<br />

session can be started even when the COBW3_START_SESSION subroutine is called.<br />

If a session has already been started, an error is returned when this subroutine is<br />

called.<br />

The data type cannot be changed after a session is established. To change the data<br />

<strong>for</strong>mat, terminate the session by calling the “COBW3_END_SESSION” And then start<br />

a new session.<br />

Format:<br />

CALL "COBW3_START_SESSION " USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-SESSION-DATA-TYPE<br />

Sets a session data type.<br />

Condition-name Value Meaning<br />

COBW3–SESSION-DATA-GROUPITEM “0” Uses a group item as the session<br />

data.<br />

COBW3-SESSION–DATA-OBJECT “1” Uses an object reference item as the<br />

session data.<br />

• COBW3-SESSION-TIMEOUT<br />

Specifies a session timeout (in seconds). This is the maximum waiting period<br />

allowed, from the time when “COBW3_FREE” is called to the time when<br />

“COBW3_INIT” is called in the next thread of the same session, be<strong>for</strong>e<br />

automatic session termination occurs.<br />

Value Meaning<br />

1 to 999999 Timeout processing is executed when the specified time (in seconds) has<br />

passed.<br />

Process Result Data:<br />

None


COBW3_END_SESSION<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 61<br />

Terminates the current session. Also, it deletes in<strong>for</strong>mation set during session<br />

establishment.<br />

Notes: Call this subroutine be<strong>for</strong>e using the “COBW3_PUT_TEXT,”<br />

“COBW3_PUT_HTML” or “COBW3_FREE.” Once any of these subroutines is used, no<br />

session can be terminated even if the COBW3_END_SESSION subroutine is called.<br />

If the session has already been terminated, an error is returned when this subroutine<br />

is called.<br />

Formats:<br />

CALL "COBW3_END_SESSION " USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

None<br />

Process Result Data:<br />

None<br />

COBW3_SET_SESSION_DATA<br />

Registers session data to be used in the current session. The registered data is<br />

shared within the same session.<br />

Note: Call this subroutine when the session has been established. No session data<br />

can be registered if it is called be<strong>for</strong>e or after the session.<br />

The session data <strong>for</strong>mat cannot be changed when a session is established.<br />

Formats:<br />

CALL "COBW3_SET_SESSION_DATA" USING COBW3 session-data<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-SESSION-DATA-SIZE<br />

Specifies a session data length (in bytes). It is valid only if the COBW3-<br />

SESSION-DATA-GROUPITEM has been set in the session data <strong>for</strong>mat during<br />

session startup.<br />

Value Meaning<br />

1 to 999999999 Registers a session data in the specified length (in bytes).<br />

• Session data<br />

Specifies session data to be registered. It can be a group item or an object<br />

reference item, depending on the session data <strong>for</strong>mat.<br />

Notes: When specifying a group item in the session data, you cannot specify an<br />

object reference item or pointer data item as a subordinate elementary item.


62 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

When an object reference item is specified in the session data, the object class<br />

identified by the object reference item must inherit the COBW3-SESSION-ADAPTER<br />

class.<br />

If you have specified an object reference item in the session data, always assign a<br />

NULL object to the object reference item be<strong>for</strong>e its thread ends. If the NULL object<br />

is not assigned, the object may remain in memory after the session has ended. This<br />

may cause a memory shortage.<br />

If the session data to be registered differs from the session data <strong>for</strong>mat which has<br />

been set during session startup, the Web application operations are unreliable.<br />

Process Result Data:<br />

None<br />

COBW3_GET_SESSION_DATA<br />

Gets session data registered in the current session.<br />

Notes: Call this subroutine when the session is established. No session data can be<br />

obtained if this subroutine is called be<strong>for</strong>e startup of a session or after the end of the<br />

session.<br />

The session data <strong>for</strong>mat cannot be changed after the session is established.<br />

Format:<br />

CALL "COBW3_GET_SESSION_DATA" USING COBW3 session-data<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-SESSION-DATA-SIZE<br />

Specifies a group item length (in bytes) to store the obtained session data. It is<br />

valid only if COBW3-SESSION-DATA-GROUP has been set as the session data<br />

<strong>for</strong>mat during session startup.<br />

Value Meaning<br />

1 to 999999999 Gets the specified length of session data. If it differs from the session<br />

data registered in the session, an error is returned.<br />

• Session data<br />

Specifies a data item to store the session data obtained. It can be a group item<br />

or an object reference item, depending on the session data <strong>for</strong>mat.<br />

Notes: If an object reference item has been registered in the session data, the<br />

object reference item must be initialized by the NULL object and set in the calling<br />

parameter of this subroutine. If not initialized by the NULL object, no session data<br />

can be obtained. When specifying an object reference item in the session data,<br />

specify the object reference item with the USAGE OBJECT REFERENCE clause and<br />

specify no other items.<br />

If the session data obtained differs from the session data <strong>for</strong>mat which has been set<br />

during session startup, the Web application operations are unreliable.<br />

Process Result Data:<br />

None


COBW3_ALTER_SESSION_TIMEOUT<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 63<br />

Alters the current session timeout (in seconds).<br />

Notes: Call this subroutine when the session is established. No session timeout can<br />

be altered if the subroutine is called be<strong>for</strong>e or after the session.<br />

Format:<br />

CALL "COBW3_ALTER_SESSION_TIMEOUT" USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

• COBW3-SESSION-TIMEOUT<br />

Specifies a session timeout (in seconds). This is the maximum waiting period<br />

from the time when the “COBW3_FREE” is called to the time when the<br />

“COBW3_INIT” is called in the next thread of the same session.<br />

Value Meaning<br />

1 to 999999 Timeout processing is executed when the specified time (in seconds) has<br />

passed.<br />

Process result data:<br />

None<br />

COBW3_GET_SESSION_INFO<br />

Gets the current session in<strong>for</strong>mation.<br />

Format:<br />

CALL "COBW3_GET_SESSION_INFO " USING COBW3.<br />

COBW3 Data <strong>for</strong> Calls:<br />

None<br />

Process Result Data:<br />

• COBW3-SESSION-TIMEOUT<br />

Gets the timeout (in seconds) <strong>for</strong> the current session.<br />

• COBW3-SESSION-ID<br />

Gets the current session identification (ID) value.<br />

• COBW3-SESSION-DATA-SIZE<br />

Gets the data length (in bytes) of the current session. It can be obtained only<br />

when COBW3-SESSION-DATA-GROUPITEM has been set <strong>for</strong> the session data<br />

<strong>for</strong>mat during session startup. Zero (0) is set if COBW3-SESSION-DATA-OBJECT<br />

is set <strong>for</strong> the session data <strong>for</strong>mat.<br />

• COBW3-SESSION-DATA-TYPE<br />

Sets a data type of the current session.


64 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Condition-name Value Meaning<br />

COBW3-SESSION-DATA–GROUPITEM “0” A group item is used as the session<br />

data.<br />

COBW3-SESSION–DATA-OBJECT “1” An object reference item is used as the<br />

session data.<br />

• COBW3-SESSION-STATUS<br />

Sets the current session status.<br />

Condition-name Value Meaning<br />

COBW3-SESSION-STATUS-NON “0” The session is not started yet or<br />

already ended.<br />

COBW3-SESSION–STATUS-STARTED “1” The session has been started up.<br />

<strong>SAF</strong>-Specific <strong>Subroutines</strong><br />

COBW3_<strong>SAF</strong>_GET_PARM, COBW3_<strong>SAF</strong>_GET_PARM_XX,<br />

COBW3_<strong>SAF</strong>_GET_PARM_NX, COBW3_<strong>SAF</strong>_GET_PARM_XN,<br />

COBW3_<strong>SAF</strong>_GET_PARM_NN<br />

Search <strong>for</strong> an NES parameter name in the NES parameter in<strong>for</strong>mation and get the<br />

parameter value corresponding to the NES parameter name.<br />

Each subroutine has the following meaning.<br />

ASCII environment:<br />

• COBW3_<strong>SAF</strong>_GET_PARM<br />

Searches <strong>for</strong> an NES parameter name consisting of an alphanumeric character<br />

string, and returns the corresponding NES parameter value in an alphanumeric<br />

character string.<br />

Unicode environment:<br />

• COBW3_<strong>SAF</strong>_GET_PARM_XX<br />

Searches <strong>for</strong> an NES parameter name consisting of an alphanumeric character<br />

string, and returns the corresponding NES parameter value in an alphanumeric<br />

character string.<br />

• COBW3_<strong>SAF</strong>_GET_PARM_NX<br />

Searches <strong>for</strong> an NES parameter name consisting of a national character string,<br />

and returns the corresponding NES parameter value in an alphanumeric<br />

character string.<br />

• COBW3_<strong>SAF</strong>_GET_PARM_XN<br />

Searches <strong>for</strong> an NES parameter name consisting of an alphanumeric character<br />

string, and returns the corresponding NES parameter value in a national<br />

character string.


Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 65<br />

• COBW3_<strong>SAF</strong>_GET_PARM_NN<br />

Searches <strong>for</strong> an NES parameter name consisting of a national character string,<br />

and returns the corresponding NES parameter value in a national character<br />

string.<br />

Padding characters <strong>for</strong> storing the obtained NES parameter value are blank.<br />

Note: As the NES parameter name is case-sensitive, the ALPHAL (WORD) or<br />

NOALPHAL compiler option must be used if necessary.<br />

Formats:<br />

•<br />

•<br />

CALL "COBW3_<strong>SAF</strong>_GET_PARM" USING COBW3<strong>SAF</strong>.<br />

CALL "COBW3_<strong>SAF</strong>_GET_PARM_XX" USING COBW3<strong>SAF</strong>.<br />

CALL "COBW3_<strong>SAF</strong>_GET_PARM_NX" USING COBW3<strong>SAF</strong>.<br />

CALL "COBW3_<strong>SAF</strong>_GET_PARM_XN" USING COBW3<strong>SAF</strong>.<br />

CALL "COBW3_<strong>SAF</strong>_GET_PARM_NN" USING COBW3<strong>SAF</strong>.<br />

COBW3 Data <strong>for</strong> Calls:COBW3-<strong>SAF</strong>-PARM-NAME, COBW3-<strong>SAF</strong>-PARM-NAME-N<br />

Set a NES parameter name to be located.<br />

Specify the NES parameter name in COBW3-<strong>SAF</strong>-PARM-NAME <strong>for</strong><br />

COBW3_<strong>SAF</strong>_GET_PARM, COBW3_<strong>SAF</strong>_GET_PARM_XX or<br />

COBW3_<strong>SAF</strong>_GET_PARM_XN.<br />

Specify it in COBW3-<strong>SAF</strong>-PARM-NAME-N <strong>for</strong> COBW3_<strong>SAF</strong>_GET_PARM_NX or<br />

COBW3_<strong>SAF</strong>_GET_PARM_NN.<br />

COBW3-<strong>SAF</strong>-PARM-NAME-LENGTH [Optional]<br />

Sets a length of NES parameter character string (in bytes) <strong>for</strong> search of a NES<br />

parameter name if it ends with a valid space.<br />

Value Meaning<br />

0 The NES parameter name of the entire length of character string except <strong>for</strong><br />

spaces. However, if the COBW3-<strong>SAF</strong>-PARM-NAME or COBW3-<strong>SAF</strong>-PARM-<br />

NAME-N is only spaces, the length of character string is considered to be zero.<br />

1 to 64 The specified length of NES parameter name is searched.


66 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Process Result Data:<br />

• COBW3-<strong>SAF</strong>-SEARCH-FLAG<br />

•<br />

•<br />

Condition-name Value Meaning<br />

COBW3-<strong>SAF</strong>-PARM–FLAG-NON “0” The specified NES name is not found.<br />

COBW3-<strong>SAF</strong>-PARM–FLAG-EXIST “1” The specified NES name has been found.<br />

COBW3-<strong>SAF</strong>-PARM-VALUE, COBW3-<strong>SAF</strong>-PARM-VALUE-N<br />

Set an NES parameter value corresponding to the NES parameter name to be<br />

located.<br />

The NES parameter value is set in COBW3-<strong>SAF</strong>-PARM-VALUE <strong>for</strong><br />

COBW3_<strong>SAF</strong>_GET_PARM, COBW3_<strong>SAF</strong>_GET_PARM_XX or<br />

COBW3_<strong>SAF</strong>_GET_PARM_NX.<br />

Set it in COBW3-<strong>SAF</strong>-PARM-VALUE-N <strong>for</strong> COBW3_<strong>SAF</strong>_GET_PARM_XN or<br />

COBW3_<strong>SAF</strong>_GET_PARM_NN.<br />

COBW3-<strong>SAF</strong>-PARM-LENGTH<br />

Sets a length of character string of NES parameter value (in bytes)<br />

corresponding to the NES parameter name to be searched.<br />

COBW3_<strong>SAF</strong>_GET_BASENAME<br />

Gets an application name to be set in the URL.<br />

Note: As an application is identified by its MIME type (extender) in NES, the<br />

application name can be used as part of input data <strong>for</strong> process switching. The<br />

application name can contain any character. However, the operations are unreliable<br />

if a character other than “a” to “z,” “A” to “Z,” “0” to “9,” “-“ (hyphen) or “_”<br />

(underscore) is included.<br />

Format:<br />

CALL "COBW3_<strong>SAF</strong>_GET_BASENAME " USING COBW3<strong>SAF</strong>.<br />

COBW3 Data <strong>for</strong> Calls:<br />

None<br />

Process Result Data:<br />

• COBW3-<strong>SAF</strong>-BASENAME<br />

Gets an application name.<br />

•<br />

COBW3-<strong>SAF</strong>-BASENAME-LENGTH<br />

Gets the length the application name (in bytes).


Data Length Restrictions of <strong>SAF</strong> <strong>Subroutines</strong><br />

The data length is limited as follows in <strong>SAF</strong> subroutines.<br />

Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong> 67<br />

Item Value<br />

Maximum length of Web parameter (*1) 1073741822bytes<br />

Maximum length of character string of Web parameter NAME 1024 bytes<br />

Maximum length of character string of Web parameter VALUE 1024 bytes<br />

Maximum record length of result output page (file) to be specified<br />

in COBW3-HTML-FILENAME (*2)<br />

Length of a single line of result output page after updating of<br />

conversion data<br />

1024 bytes<br />

3072 bytes<br />

*1 The data <strong>for</strong>mat of the Web parameter is different according to the specification<br />

of ENCTYPE of the FORM tag. The data of the file up-loading etc. besides NAME and<br />

VALUE are included in the Web parameter. Moreover, when the memory which can<br />

be used is a little, data might not be able to be received even when the size of data<br />

does not exceed the fixed quantity limitation because the Web parameter is acquired<br />

on the memory of the machine with WWW Server. There<strong>for</strong>e, you should display the<br />

size of the file which can be up-loaded to the Web page <strong>for</strong> the invoking application,<br />

or display not to up-load the file which exceeds the limitation Web page <strong>for</strong> invoking<br />

application if it is necessary. Refer to the book or the homepage, etc. to explain<br />

HTML <strong>for</strong> details of the data <strong>for</strong>mat of the Web parameter.<br />

*2 If an HTML document is created by use of a commercial HTML editor, the length<br />

of a line may exceed 1024 bytes. For use with <strong>SAF</strong> subroutines, rearrange the HTML<br />

to reduce the maximum line length to 1024 bytes, using a text editor.<br />

Classes Provided by <strong>SAF</strong> <strong>Subroutines</strong><br />

The <strong>SAF</strong> subroutines provide the following classes <strong>for</strong> use by session management<br />

functions.<br />

COBW3-SESSION-ADAPTER class<br />

Used to manage an object registered as the session data. The object to be<br />

registered in the session data must be generated from a class that inherits this class.<br />

Also, timeout processing must be written in the method which has overwritten the<br />

SWEEP-SESSION method of this class by use of OVERRIDE clause.<br />

Note: Timeout processing can be used only when an object reference item is<br />

registered in the session data.<br />

No <strong>SAF</strong> subroutine can be called by timeout processing.<br />

Factory method:<br />

None


68 Chapter 3. How to Use <strong>SAF</strong> <strong>Subroutines</strong><br />

Object method:<br />

• SWEEP-SESSION<br />

This method is called when a session is timed out. It is used to per<strong>for</strong>m<br />

processing such as file closing and database (DB) commitment/rollback.<br />

Method argument:<br />

None<br />

Method return in<strong>for</strong>mation:<br />

None<br />

Note:<br />

• If a session is timed out, the <strong>SAF</strong> subroutine calls the SWEEP-SESSION method<br />

and assigns a NULL object to the object reference item which has been<br />

registered in the session data.<br />

• If the default SWEEP-SESSION method is not replaced by a user-written method,<br />

nothing is executed by the SWEEP-SESSION method.<br />

• The COBW3-SESSION-ADAPTER class inherits the FJBASE class.<br />

Example:<br />

[COBOL program]<br />

IDENTIFICATION DIVISION.<br />

CLASS-ID. SESSDATA INHERITS COBW3-SESSION-ADAPTER.<br />

:<br />

IDENTIFICATION DIVISION.<br />

OBJECT.<br />

:<br />

IDENTIFICATION DIVISION.<br />

METHOD-ID. SWEEP-SESSION OVERRIDE.<br />

DATA DIVISION.<br />

:<br />

PROCEDURE DIVISION.<br />

:<br />

* Write down timeout processing if necessary.<br />

:<br />

END METHOD SWEEP-SESSION<br />

:<br />

END OBJECT.<br />

END CLASS SESSDATA.


Chapter 4. Generating and Executing a Web<br />

Application<br />

This chapter explains the basic method <strong>for</strong> compilation, linkage, and execution of<br />

Web applications using <strong>SAF</strong> subroutines.<br />

For details of compile options and link options that are not explained in this chapter,<br />

refer to the <strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>.<br />

This section gives basic explanations of how to compile, link, and execute the Web<br />

application. For compile options and link options that are not explained in this<br />

section, see "<strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>."


70 Chapter 4. Generating and Executing a Web Application<br />

Executing a Web Application<br />

To execute a Web application, follow the procedure below.<br />

1. Compile and link the program.<br />

For details, see "Compiling and Linking".<br />

2. Set the environment.<br />

- Set up the environment <strong>for</strong> the NES. For details, see "NES Setup".<br />

- Set up the environment <strong>for</strong> <strong>SAF</strong> subroutines. For details, see "Environment<br />

Variable Setup <strong>for</strong> <strong>SAF</strong> <strong>Subroutines</strong>".<br />

3. Execute the Web application.<br />

Display the Web page that invokes the application (HTML document) and start<br />

the application.<br />

For details, see "Executing a Web application".<br />

Compiling and Linking<br />

A program created that uses <strong>SAF</strong> subroutines is compiled and linked as shown below.<br />

In the example, the file name is MainProc.cob and the entry-name is <strong>SAF</strong>-MAIN. If<br />

the Project Manager is used, use the build utility of the project manager <strong>for</strong><br />

compiling and linking.<br />

• Compile the COBOL source program.<br />

Two methods of compiling the COBOL source program are provided: By<br />

executing the WINCOB command from the Project Manager and by using the<br />

compile command at the command prompt. This section shows an example<br />

using the compile command .<br />

For details of compiling using the WINCOB command and compiling commands,<br />

see "<strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>."<br />

COBOL32 –WC, "THREAD(MULTI)" MainProc.cob<br />

Notes: <strong>SAF</strong> is a multi-thread application, so the compile option THREAD (MULTI)<br />

must be specified. In order to distinguish upper-case letters/lower-case letters of an<br />

application entry-name, or NES parameter name accessed by a subroutine such as<br />

COBW3_<strong>SAF</strong>_GET_PARM_XX, specify the compile option ALPHAL (WORD) or<br />

NOALPHAL .<br />

• Link the COBOL object program. (.DLL generation)<br />

Two methods of linking the object program are provided: By executing the<br />

WINLINK command from the Project Manager and by using the link command at<br />

the command prompt. In this section, an example of linking by using the link<br />

command is given. For details of linking by using the WINLINK command and<br />

link commands, see "Net COBOL <strong>User's</strong> <strong>Guide</strong>."<br />

The .DLL generated in this example is <strong>SAF</strong>SMPL.dll.<br />

The link operation is as follows:


NES Settings<br />

Chapter 4. Generating and Executing a Web Application 71<br />

LINK /DLL /OUT:<strong>SAF</strong>SMPL.dll MainProc.obj<br />

F3BICBDM.obj F3BINSRT.lib F3BICIMP.lib KERNEL32.LIB LIBC.LIB<br />

/ENTRY:COBDMAIN<br />

The initialization file (COBOL85.CBR) can be allocated in the same folder as the .DLL,<br />

regardless of the current folder, by linking F3BICBDM. obj and<br />

specifying/ENTRY:COBDMAIN. It is very useful that the initial file can be allocated in<br />

the same folder as the .DLL since the current folder of the application under the<br />

server such as an NES is undefined. For details, see "<strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>.<br />

The following items must be set <strong>for</strong> NES when executing the Web application.<br />

• Define the <strong>SAF</strong> director to NES.<br />

• Define the Web application to the <strong>SAF</strong> director.<br />

• Register the MIME type of the application with NES.<br />

Defining the <strong>SAF</strong> Director to NES<br />

Note: Modification of the obj.conf file is not reflected to NES until NES is restarted.<br />

Initialize the <strong>SAF</strong> director in NES by editing obj.conf file in the folder where NES is<br />

installed.<br />

Open obj.conf file by using an adequate text editor. Locate lines starting with “Init”<br />

near the beginning of the file. Add the following description at the end of lines. In<br />

this example, the folder in which the COBOL is installed is set to C:\COBOL. The <strong>SAF</strong><br />

director is in that folder.<br />

Init fn= "load-modules" shlib="C:/COBOL/F3BIN<strong>SAF</strong>.dll"<br />

funcs="COBOL_Init,COBOL_Per<strong>for</strong>m"<br />

Notes:<br />

•<br />

•<br />

•<br />

Normally, a setting is written on a single line. When writing it over multiple<br />

lines, a space or tab must be written at the beginning of each continuation line.<br />

Do not edit other lines starting with Init . NES may fail to initialize.<br />

Backup of obj.conf file be<strong>for</strong>e editing is recommended.<br />

Defining the Web Application to the <strong>SAF</strong> Director<br />

In order to execute the Web application in NES, define the Web application to the<br />

<strong>SAF</strong> director.<br />

When NES is started, the <strong>SAF</strong> director loads the Web application and executes the<br />

loaded Web application in response to each request.


72 Chapter 4. Generating and Executing a Web Application<br />

• Load specification of Web application when NES is started<br />

Add the following description after the <strong>SAF</strong> director definition in obj.conf file.<br />

Init fn="COBOL_Init" load=" dll name, entry-name [;dll name, entry-name]…"<br />

[env="environment setup file"]<br />

[sev="log output severity of <strong>SAF</strong> director”]<br />

In the following example, settings are as follows:<br />

•<br />

•<br />

•<br />

The folder to which the Web application is allocated is C:\COBAPL.<br />

The Web application name and entry-name are <strong>SAF</strong>SMPL1.DLL, SAMPLE 1, and<br />

<strong>SAF</strong>SMPL2.DLL, SAMPLE2.<br />

The environment setup file is C:\COBAPL\SETUP1.BAT and log output severity of<br />

<strong>SAF</strong> director logging is set to 1.<br />

Init fn= "COBOL_Init"<br />

load="C:/COBAPL/<strong>SAF</strong>SMPL1.dll,SAMPLE1;C:/COBAPL/<strong>SAF</strong>SMPL2.dll,SAMPLE2"<br />

env="C:/COBAPL/SETUP1.BAT" sev="1"<br />

Note: For descriptions of the environment setup file, see "COBOL_Init".<br />

• Specifying Web application execution<br />

Specify the Web application to be started in response to each request. Add the<br />

following description to an adequate position in lines starting with “Service” in<br />

obj.conf.<br />

Service type="MIME type" fn="COBOL_Per<strong>for</strong>m" app="DLL name, entry-name"<br />

[sev="log output severity of <strong>SAF</strong> director"]<br />

Note: Add the description above to the position enclosed with tags and . When using another object tag, see the NES<br />

manual. Moreover, if two or more Web applications can be started, the description<br />

above of each application is added. At this time, the MIME type specifies the one<br />

different in each Web application.<br />

In the following example, settings are as follows:<br />

• MIME type is "magnus-internal/cob-app1."<br />

• The folder to which the Web application is installed is C:\COBAPL.<br />

• The Web application name and entry-name is C: \COBAPL\<strong>SAF</strong>SMPL1.DLL,<br />

SAMPLE 1.<br />

• The log output severityof the <strong>SAF</strong> director is set to 1.<br />

service type="magnus-internal/cob-appl"<br />

fn="COBOL_Per<strong>for</strong>m" app="C:/COBAPL/<strong>SAF</strong>SMPL1.DLL,SAMPLE1"<br />

sev="1"<br />

Note: A character-string "magnus-internal/" must be registered with the NES as a<br />

MIME type.


MIME Type Setup<br />

Chapter 4. Generating and Executing a Web Application 73<br />

Register the MIME type using the NES administration page. First open the "Netscape<br />

Server Administration" page.<br />

Pressing the Web site button ("cobol-svr" button in the figure above) on this page<br />

displays the "Server Preference" page. Click "MIME Types" and "Global MIME Types"<br />

page is displayed.


74 Chapter 4. Generating and Executing a Web Application<br />

Set a new MIME type on this page. Specify the MIME type used in Section "Defining<br />

the Web application to the <strong>SAF</strong> director." Specify "magnus-internal/cob-app1." Also<br />

set the File Suffix in order to specify the Web application. Specify "cobap1" here.<br />

Any character-string may be used as the file suffix as long as it does not duplicate a<br />

previous suffix.<br />

The “type” must be specified to a category.<br />

Pressing "New Type" button after entering the data displays the "Save and Apply<br />

Changes" page. Then, press the "Save and Apply" or "Save" button to save the<br />

setup.


Chapter 4. Generating and Executing a Web Application 75<br />

Environment Variable Setup <strong>for</strong> <strong>SAF</strong> Subroutine<br />

In order to execute the Web application using the <strong>SAF</strong> subroutine, it is necessary to<br />

set the following execution environment in<strong>for</strong>mation in an environment variable, or in<br />

the <strong>SAF</strong> director environment setting, or initialization file (COBOL85. CBR) . When<br />

using an initialization file , link each application with F3BICBDM.obj so that an<br />

initialization file in the application folder can be referenced. The use of an<br />

environment setup file of the <strong>SAF</strong> director is recommended, since an initialization file<br />

(COBOL85.CBR) is not validated until the COBOL program is executed <strong>for</strong> the first<br />

time. For description of the environment setup file, see "COBOL_Init" in Chapter 4.<br />

Notes: The NES deletes system environment variables which the NES does not<br />

require from the environment variable block. Thus, environment variables needed by<br />

the <strong>SAF</strong> subroutine and the Web application cannot be accessed even though they<br />

are set as system environment variables. For this case, use environment setup file of<br />

the <strong>SAF</strong> director or initialization file (COBOL85.CBR) <strong>for</strong> the environment variables<br />

that are required by the application. For environment variables used by the NES, see<br />

the NES manual.<br />

When the environment variable specified that system environment variable,<br />

environment setup file of the <strong>SAF</strong> director and initialization file (COBOL85.CBR)<br />

overlaps, the priority level becomes as follows.<br />

Initialization file (COBOL85.CBR) > environment setup file of <strong>SAF</strong> director > system<br />

environment variable<br />

The one to be set in System environment variable or environment setup file of the<br />

<strong>SAF</strong> director


76 Chapter 4. Generating and Executing a Web Application<br />

PATH<br />

Include the path of the dynamic-link library (.DLL) used by the Web application.<br />

The one to be set in environment setup file of <strong>SAF</strong> director or<br />

initialization file (COBOL85.CBR)<br />

@CBR_ATTACH_TOOL=TEST [Start parameter]<br />

Specifies whether to start (TEST) the debugger at the time of application execution.<br />

If there is a debugger start parameter, it can be specified after "TEST" in this<br />

variable.<br />

Please refer to Chapter 5, "Debugging a <strong>SAF</strong> Application" <strong>for</strong> more in<strong>for</strong>mation.<br />

@MessOutFile = file name<br />

Specifies the name of the file to which the execution message to be output from the<br />

COBOL run time system is stored. This specification suppresses the message box<br />

being output to the screen. Use the absolute path <strong>for</strong> the file name. If the file<br />

already exists, messages are added to the end of file .<br />

@WinCloseMsg = OFF<br />

Specifies whether to display the confirmation message (ON) or not (OFF) when<br />

closing the window. When executing the application on the Web application, elect<br />

not to display the confirmation message (OFF).<br />

@CBR_<strong>SAF</strong>_LOGFILE = log file name<br />

Specifies the <strong>SAF</strong> log file output by the <strong>SAF</strong> subroutine. It is useful when debugging<br />

<strong>SAF</strong> failures. Use the absolute path <strong>for</strong> the file name. If the file is not specified, no<br />

log is output.<br />

@CBR_<strong>SAF</strong>_SEVERITY = severity<br />

Specifies the severity of log in<strong>for</strong>mation to be output by the <strong>SAF</strong> subroutine. The<br />

following values can be specified. If any other value is specified, or when nothing is<br />

specified, 0 is assumed.<br />

0 Only fatal error messages are output.<br />

1 In addition to fatal errors, severe error messages are output.<br />

2 In addition to severe errors, an warning messages are output.<br />

3 In addition to warnings, a trace of the <strong>SAF</strong> subroutine is output.<br />

Notes:<br />

As more logging is enabled, the slower the application runs . Specify the value<br />

needed to log only as much detail as required. We do not recommend specifying 3<br />

unless all other options are insufficient.<br />

For other execution environment in<strong>for</strong>mation , see "<strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>."


Executing a Web Application<br />

Chapter 4. Generating and Executing a Web Application 77<br />

Place the MIME extension used by the Web applicationin the ACTION attribute of the<br />

FORM tag in the Web page that invokes the application as follows:<br />

<br />

<br />

sample <br />

<br />

<br />

:<br />

<br />

<br />

<br />

Allocate this Web page (HTML document) in an appropriate document directory of<br />

NES and start the application by using it.<br />

Note: Web applications may be frequently modified during testing. In operation<br />

environment, however, NES keeps the first copy of the application that it loads in<br />

memory, so that NES must be stopped and restarted to load the modified version. It<br />

is possible to stop and restart the NES from the NES administration screen.<br />

<strong>SAF</strong> Director Reference<br />

COBOL_Init<br />

Specify the Web application to be loaded by NES and the environment setup file <strong>for</strong><br />

the application.<br />

Format:<br />

Init fn="COBOL_Init"<br />

[load="DLL name1, entry-name 11 [, entry-name 12]…[;DLL name 2, entry-name<br />

21 [, entry-name 22]…]…"]<br />

[env="environment setup file"] [sev="log output severity of <strong>SAF</strong> director"]<br />

Parameters:<br />

• load<br />

Target DLL names <strong>for</strong> loading and entry-names scheduled <strong>for</strong> execution are<br />

listed. Use an absolute path <strong>for</strong> the .DLL name. Use commas <strong>for</strong> delimiting<br />

entry-names belonging to the .DLL. Specify at least one entry-name <strong>for</strong> a .DLL.<br />

To specify multiple .DLL names, use a semi-colon.<br />

•<br />

env<br />

Specify an absolute path <strong>for</strong> an environment setup file. In the environment<br />

setup file, specify variables as follows:<br />

SET environment variable name = environment variable value<br />

Given below is an example of environment setup file description when the Web<br />

application is stored in "C:\COBAP."


78 Chapter 4. Generating and Executing a Web Application<br />

set PATH=C:\COBAP;%PATH%<br />

rem **For COBOL setting **<br />

set @WinCloseMsg=OFF<br />

set @MessOutFile=C:\COBAP\LOG\cobol.txt<br />

rem ** For <strong>SAF</strong> subroutines settings **<br />

set @CBR_<strong>SAF</strong>_LOGFILE=C:\COBAP\LOG\safap.txt<br />

set @CBR_<strong>SAF</strong>_SEVERITY=0<br />

To write a comment line, write REM at the beginning of the line.<br />

The difference between uppercase and lowercase letters is not significant in the<br />

“SET” and “REM” keywords, But they are in environment variable names and<br />

environment variable values.<br />

Notes: To write COBOL_Init over multiple lines when specifying an environment<br />

setup file <strong>for</strong> env, write the environment setup file only <strong>for</strong> the first COBOL_Init or<br />

write the same environment setup file <strong>for</strong> multiple lines. If environment setup files<br />

written in multiple COBOL_Init lines are different, results are not guaranteed.<br />

• sev<br />

Specify the severity of log in<strong>for</strong>mation to be output by the <strong>SAF</strong> director. The<br />

following values can be specified . If any other value is specified, or if nothing is<br />

specified, 0 is assumed.<br />

0 Only fatal error messages are output.<br />

1 In addition to fatal messages, severe error messages are output.<br />

2 In addition to severe messages, warning messages are output.<br />

3 In addition to warning messages, a trace of the <strong>SAF</strong> subroutine is output.<br />

The log in<strong>for</strong>mation that is output by the <strong>SAF</strong> director is recorded in the same place<br />

as the error log of NES. To view the <strong>SAF</strong> director and NES error logs, use the<br />

administration page of the NES <strong>for</strong> reference.<br />

Notes: Each specification of severity by sev is valid in each COBOL_Init. This<br />

specification has nothing to do with the severity (env) specified in COBOL_Per<strong>for</strong>m<br />

The severity of log in<strong>for</strong>mation to be specified here does not have any effect on the<br />

log in<strong>for</strong>mation that is output by the <strong>SAF</strong> subroutine. For the log in<strong>for</strong>mation that is<br />

output by the <strong>SAF</strong> subroutine, see "Environment Variable Setup <strong>for</strong> <strong>SAF</strong> <strong>Subroutines</strong>".<br />

As more logging is enabled, the slower the <strong>SAF</strong> Director runs . Specify the value<br />

needed to log only as much detail as required. We do not recommend specifying 3<br />

unless all other options are insufficient.<br />

Notes: NES deletes environment variables in the system, except what NES requires.<br />

Thus, use the environment setup file <strong>for</strong> the environment variables that are required<br />

by the application.<br />

COBOL_Per<strong>for</strong>m<br />

Execute the Web application. If the Web application has been loaded by<br />

COBOL_Init, the application is executed. If it has not been loaded, it is loaded at this<br />

time. After the application is loaded, it stays in NES while being loaded.


Format:<br />

Chapter 4. Generating and Executing a Web Application 79<br />

Service [type="MIME type"] fn="COBOL_Per<strong>for</strong>m" app="DLL name,<br />

entry-name"<br />

[sev="log output severity of <strong>SAF</strong> director"]<br />

Parameters:<br />

•<br />

•<br />

app<br />

Specify the .DLL name and an entry-name of the COBOL application to be<br />

executed. Specify an absolute path as a DLL name in the same way as in<br />

COBOL_Init.<br />

sev<br />

Specify the severity of log in<strong>for</strong>mation to be output by the <strong>SAF</strong> director. The<br />

following values can be specified. If any value besides those is specified, or<br />

when nothing is specified, it is regarded as 0 specified.<br />

0 Only fatal error messages are output.<br />

1 In addition to fatal messages, severe error messages are output.<br />

2 In addition to severe messages, warning messages are output.<br />

3 In addition to warning messages, a trace of the <strong>SAF</strong> Director is output.<br />

The log in<strong>for</strong>mation that is output by the <strong>SAF</strong> director is recorded in the same place<br />

as the error log of NES. To view the <strong>SAF</strong> director and NES error logs, use the<br />

administration page of the NES <strong>for</strong> reference.<br />

Notes: Each specification of severity by sev is valid in each COBOL_Per<strong>for</strong>m. This<br />

specification has nothing to do with the severity (env) specified in COBOL_Init.<br />

The severity of log in<strong>for</strong>mation to be specified here does not have any effect on the<br />

log in<strong>for</strong>mation that is output by <strong>SAF</strong> subroutine. For the log in<strong>for</strong>mation that is<br />

output by the <strong>SAF</strong> subroutine, see "Environment Variable Setup <strong>for</strong> <strong>SAF</strong> <strong>Subroutines</strong>".<br />

As more logging is enabled, the slower the <strong>SAF</strong> Director runs . Specify the value<br />

needed to log only as much detail as required. We do not recommend specifying 3<br />

unless all other options are insufficient.<br />

Note: For other parameters that can be specified on “Service” lines, see the NES<br />

manual.


80 Chapter 4. Generating and Executing a Web Application


Chapter 5. Debugging a <strong>SAF</strong> Application<br />

The following resources are provided <strong>for</strong> checking the execution of a <strong>SAF</strong> application<br />

during testing or when an error occurs.<br />

• Log in<strong>for</strong>mation<br />

• The Interactive Debugger<br />

• Displaying errors detected by <strong>SAF</strong> subroutines on the Web page<br />

• Displaying Working-Storage data or messages on the Web page<br />

The following sections explain the use of each method.


82 Chapter 5. Debugging a <strong>SAF</strong> Application<br />

Referring to the Log In<strong>for</strong>mation<br />

<strong>SAF</strong> subroutines contain a logging feature that may be turned on or off by an<br />

environment variable. For setting this feature, see "Environment variable setup <strong>for</strong><br />

<strong>SAF</strong> subroutine" in Chapter 4. Since it is the log in<strong>for</strong>mation of <strong>SAF</strong> subroutines, it is<br />

not a program trace, but it provides a record of the <strong>SAF</strong> subroutine calls made by the<br />

program. The log file record <strong>for</strong>mat is as follows:<br />

Process ID thread ID year-month-day hour:minute:second severity message<br />

A concrete example of the configuration is given below.<br />

0000000188 0000000187 1999-02-02 11:48:07 02 COB-06310: COBW3: The specified<br />

conversion name has already been set. The conversion in<strong>for</strong>mation that has already<br />

been set is validated.<br />

0000000188 0000000181 1999-02-02 11:48:10 01 COB-04470: COBW3: The conversion<br />

in<strong>for</strong>mation specified could not be changed because it has not been set.<br />

To collect trace in<strong>for</strong>mation from an application, itself, use the TRACE function of<br />

COBOL. For details of the TRACE function, see "<strong>NetCOBOL</strong> Debugging <strong>Guide</strong>."<br />

For details of the log output by <strong>SAF</strong> Director, see " <strong>SAF</strong> Director Reference" in<br />

Chapter 4.<br />

Checking Execution Using the Interactive Debugger<br />

The debug the Web application generated in the COBOL, by using the debugger, use<br />

the method of starting the debugger from the program to be debugged.<br />

The Web application can be remotely debugged from the client which starts a WWW<br />

browser by using a remote debugger. Please refer to “<strong>NetCOBOL</strong> Debugging <strong>Guide</strong>”<br />

<strong>for</strong> the usage of a remote debugger.<br />

The following must be noted when debugging an application by using the interactive<br />

debugger because NES reads all Web applications into the same memory space.<br />

•<br />

•<br />

If a Web application operates incorrectly, not only the application being<br />

debugged but also other Web applications loaded at the same time and NES<br />

itself may fail. We recommend using the interactive debugger only when other<br />

Web applications are not in use. If this is successful, then you can check<br />

operations when other Web applications are active.<br />

The debugger debugs not only the Web application being tested, but also other<br />

Web applications and NES itself. If the debugger terminates, other Web<br />

applications and NES will also terminate and it will be necessary to restart NES.


Starting the Debugger<br />

To start debugging, follow the procedure below:<br />

Chapter 5. Debugging a <strong>SAF</strong> Application 83<br />

1. Compile and link the Web application.<br />

Specify the compile option and the link option <strong>for</strong> debugging and generate the<br />

Web application. For methods of compiling and linking <strong>for</strong> debugging, see<br />

"<strong>NetCOBOL</strong> Debugging <strong>Guide</strong>."<br />

2. Set the run-time environment variables.<br />

Be<strong>for</strong>e starting the debugger from a program to be debugged, you need to set<br />

the following run-time environment in<strong>for</strong>mation. For in<strong>for</strong>mation on setting the<br />

run-time environment in<strong>for</strong>mation, see "Environment variable setup <strong>for</strong> <strong>SAF</strong><br />

subroutine" in Chapter 4.<br />

@CBR_ATTACH_TOOL = TEST [start parameter]<br />

Specify whether to start (TEST) the debugger at the time of application<br />

execution. It is possible to specify the debugger start parameter, if any, after<br />

specifying "TEST." For an explanation of the start parameter, see "<strong>NetCOBOL</strong><br />

Debugging <strong>Guide</strong>."<br />

3. Log on to the computer on which the Web application to be debugged is to be<br />

executed.<br />

4. Start the web application from a WWW browser. The WWW browser need not<br />

run on the computer on which the Web application is to be executed.<br />

5. When the Web application is started, the debugger is automatically started.<br />

When the debugger is started, specify the debugging in<strong>for</strong>mation file storage<br />

folder and necessary in<strong>for</strong>mation, and then start debugging.<br />

Debugging<br />

You can debug a Web application just like any regular COBOL application using the<br />

debugger. For instructions on using the debugger, see "<strong>NetCOBOL</strong> Debugging<br />

<strong>Guide</strong>." Be<strong>for</strong>e starting debugging, however, note the following:<br />

•<br />

•<br />

•<br />

The debugger automatically interrupts the execution at the entry to the Web<br />

application to allow setting breakpoints or other options. Subsequent calls to the<br />

application are not interrupted unless at least one breakpoint is set. To interrupt<br />

the execution of a Web application loaded by the next request, specify the name<br />

of the program to be loaded at a command or in a dialog box to specify a<br />

breakpoint. For details, see "Debug functions <strong>for</strong> dynamic structured programs"<br />

in "<strong>NetCOBOL</strong> Debugging <strong>Guide</strong>."<br />

After responding to the WWW browser, the program remains running in a wait<br />

state <strong>for</strong> the next request. To per<strong>for</strong>m a debugging operation such as setting a<br />

breakpoint, select the “Break“ command from the debugger menu to interrupt<br />

program execution <strong>for</strong> debugging.<br />

When debugging, note also the followings.<br />

When using the debugger, the application takes longer time than the normal<br />

time <strong>for</strong> operation. Thus, a timeout may occur during debugging depending on<br />

the WWW browser. If it is possible to specify a timeout in the browser, change<br />

the value to an adequate value. Also change the timeout value in NES to an<br />

adequate value.


84 Chapter 5. Debugging a <strong>SAF</strong> Application<br />

•<br />

•<br />

•<br />

•<br />

Normally, when NES is fails, it is automatically restarted. When using the<br />

debugger, change NES setup if it is unnecessary that NES restart automatically.<br />

Terminating the Debugger<br />

When terminating the debugger first<br />

When the debugger terminates, NES also terminates. Thus, it is necessary to<br />

restart NES.<br />

When terminating the Web application first<br />

Stop NES. To stop NES, use the WWW browser "Netscape Server<br />

Administration" page. When you stop NES, the Web application must be running<br />

until the process is terminated.<br />

Switch the Web application as follows:<br />

Stop NES and switch the Web application, then restart NES.<br />

To stop and start NES, use the WWW browser from “Netscape Server<br />

Administration” page. When you stop NES, the Web application must be running<br />

until the process is terminated.<br />

Displaying Errors Detected by <strong>SAF</strong> <strong>Subroutines</strong><br />

To display errors detected by <strong>SAF</strong> subroutines, set the debug mode just be<strong>for</strong>e<br />

calling COBW3_INIT in the program.<br />

SET COBW3-DMODE-DBG TO TRUE.<br />

CALL "COBW3_INIT" USING COBW3.<br />

If an error is detected in a <strong>SAF</strong> subroutine , an error message is displayed in the<br />

WWW browser.<br />

If the setting <strong>for</strong> header output is not COBW3-CONTENT-TYPE-NON, it is regarded as<br />

COBW3-CONTENT-TYPE-HTML and COBW3_INIT declares the content-type.<br />

Supplements<br />

To set the debug mode, it is necessary to modify the program and regenerate the<br />

Web application. Setting the debug mode enables referring to an error message to<br />

be displayed on the WWW browser even in the log in<strong>for</strong>mation. So, we recommend<br />

using the log in<strong>for</strong>mation if you want to refer to an error message without changing<br />

the application.<br />

Notes: The COBW3-DMODE-DBG setting can not be used in a Unicode<br />

environment. Check the operation by means such as referring to the log in<strong>for</strong>mation.


Chapter 5. Debugging a <strong>SAF</strong> Application 85<br />

Displaying Working-Storage Data or Messages in a Web Page<br />

To display your own messages or data on the browser screen, use<br />

COBW3_PUT_TEXT.<br />

Notes: COBW3_PUT_TEXT can display only character data. Moreover since repeat<br />

operations of compiling and executing frequently occur, the operation becomes less<br />

efficient. There<strong>for</strong>e, in such a case, we recommend debugging by using the method<br />

of referring to the data in progress of execution by an interactive debugger.


86 Chapter 5. Debugging a <strong>SAF</strong> Application


Chapter 6. Samples<br />

This chapter explains the sample programs.<br />

Each example uses <strong>SAF</strong> subroutines to pass data between Cookie applications and to<br />

exchange in<strong>for</strong>mation with the server and the browser.


88 Chapter 6. Samples<br />

Program Files Provided<br />

•<br />

•<br />

•<br />

•<br />

•<br />

•<br />

<strong>Subroutines</strong> Used<br />

<strong>SAF</strong>MAIN.cob (COBOL source program)<br />

<strong>SAF</strong>START.htm (Web page <strong>for</strong> invoking application)<br />

<strong>SAF</strong>RPLY1.htm (Web page <strong>for</strong> processing output)<br />

<strong>SAF</strong>RPLY2.htm (Web page <strong>for</strong> processing output)<br />

<strong>SAF</strong>ERROR.htm (Web page <strong>for</strong> processing error output )<br />

COBOL85.cbr (Initialization file <strong>for</strong> program execution)<br />

The following <strong>SAF</strong> subroutines are used in the examples.<br />

• COBW3_INIT<br />

• COBW3_SET_CNV<br />

• COBW3_PUT_HTML<br />

• COBW3_RECEIVE_HEADER<br />

• COBW3_GET_REQUEST_INFO<br />

• COBW3_SET_COOKIE<br />

• COBW3_GET_COOKIE<br />

• COBW3_FREE<br />

Program Compiling<br />

The following shows how to compile a program using COBOL32 commands. If you<br />

have already copied the library file (COBW3.cbl) used by <strong>SAF</strong> subroutines to the<br />

sample folder, you can omit the “-I” option. The COBOL installation folder is<br />

“C:\COBOL” in the following examples.<br />

Program Linkage<br />

COBOL32 – IC:\COBOL –WC, "THREAD(MULTI)" <strong>SAF</strong>MAIN.cob<br />

Link and create a .DLL as follows.<br />

link /dll /out:<strong>SAF</strong>SMPL1.dll <strong>SAF</strong>MAIN.obj<br />

C:\COBOL\F3BICBDM.obj F3BINSRT.lib F3BICIMP.lib<br />

kernel32.lib libc.lib/ENTRY:COBDMAIN


Environment Setup<br />

Chapter 6. Samples 89<br />

Modify the “COBOL85.cbr” initialization file depending on your operating<br />

environment. Set up NES <strong>for</strong> execution of Web applications. For NES setup details,<br />

see “NES setup” in Chapter 4.<br />

Register the MIME extension used in the ACTION attribute of the FORM tag of the<br />

calling page in NES or modify the calling page according to the extension you have<br />

registered in NES.<br />

Sample Execution<br />

Make sure that the NESis started and display the Web page <strong>for</strong> invoking the<br />

application (<strong>SAF</strong>START.htm) in the WWW browser. Then, follow the on-screen<br />

instructions and press the “Execute” button.<br />

Supplements:<br />

If you wish to convert sample operation codes into Unicode, add the “RCS (UCS2)”<br />

compile option during program compiling and convert all HTML documents into<br />

Unicode.<br />

Note: This sample does not operate correctly if you have set the WWW browser not<br />

to accept Cookies.<br />

Explanation of Samples<br />

The following paragraphs show the Web page <strong>for</strong> invoking the application<br />

(<strong>SAF</strong>SART.htm), Web pages <strong>for</strong> processing output (<strong>SAF</strong>RPLY1.htm, <strong>SAF</strong>RPLY2.htm)<br />

and the COBOL program (<strong>SAF</strong>MAIN.cob) .<br />

Web page <strong>for</strong> invoking the application (<strong>SAF</strong>START.htm)<br />

<br />

<br />

Start screen <br />

<br />

<br />

This is a sample which is used <strong>SAF</strong> subroutine. <br />

If you confirm the operation, please press “Execute” button. <br />

If you exit, please close this browser. <br />

<br />

<br />

<br />

<br />


90 Chapter 6. Samples<br />

First Web page <strong>for</strong> processing output (<strong>SAF</strong>RPLY1.htm)<br />

<br />

<br />

First Access Screen <br />

<br />

<br />

Thank you very much <strong>for</strong> having the first time<br />

<br />

If you use continuously, please press “Execute” button. <br />

If you exit, please close this browser. <br />

<br />

<br />

<br />

<br />

<br />

Second Web page <strong>for</strong> processing result output (<strong>SAF</strong>RPLY2.htm)<br />

<br />

<br />

Screen since first time <br />

<br />

<br />

Current situation is as follows. <br />

<br />

<br />

Hostname <strong>for</strong> accessed host <br />

Browser name<br />

Access count <br />

<br />

<br />


COBOL program (<strong>SAF</strong>MAIN.cob)<br />

Chapter 6. Samples 91<br />

000010*---------------------------------------------------------*<br />

000020* All Rights Reserved, Copyright© FUJITSU LIMITED 2000-2002 *<br />

000030* *<br />

000040* Filename: <strong>SAF</strong>MAIN.cob *<br />

000050* Abstract: Example demonstrating the <strong>SAF</strong> subroutine *<br />

000060*---------------------------------------------------------*<br />

000070 identification division.<br />

000080 program-id. <strong>SAF</strong>-MAIN.<br />

000090 environment division.<br />

000100 data division.<br />

000110 working-storage section.<br />

000120 copy COBW3.<br />

000130*<br />

000140 01 HTMLFilename pic X(64).<br />

000150 01 pathName pic X(256).<br />

000160 01 pathSize pic 9(05).<br />

000170 01 copyStartPos pic 9(05).<br />

000171 01 leftLength pic 9(05).<br />

000180 01 AccessCount pic 9(05).<br />

000190*<br />

000200 linkage section.<br />

000210 01 safCtx pointer<br />

000220*<br />

000230 procedure division using safCtx.<br />

000240*<br />

000250 SafSample1-Start.<br />

000260*<br />

000270* Initialize the work area <strong>for</strong> the <strong>SAF</strong> subroutine<br />

000280 move low-value to COBW3.<br />

000290 set COBW3-CONTEXT to safCtx.<br />

000300*<br />

000310* Initialize the <strong>SAF</strong> subroutine work environment and obtain<br />

000320* a Web parameter.<br />

000330 call "COBW3_INIT" using COBW3.<br />

000340*<br />

000350 move space to pathName.<br />

000360*<br />

000370 move "Your Access Counter" to COBW3-COOKIE-NAME.<br />

000380 call "COBW3_GET_COOKIE" using COBW3.<br />

000390 if program-status not = zero then<br />

000400 move "<strong>SAF</strong>ERROR.htm" to HTMLFilename<br />

000410 per<strong>for</strong>moutputScreenProc<br />

000420 else if COBW3-SEARCH-FLAG-NON then<br />

000430 move 1 to COBW3-COOKIE-VALUE<br />

000440 per<strong>for</strong>m entryAccessCounterProc<br />

000450 move "<strong>SAF</strong>RPLY1.htm" to HTMLFilename<br />

000460 per<strong>for</strong>m outputscreenProc<br />

000470 else<br />

000480 per<strong>for</strong>m outputContinuousScreenProc.<br />

000490 end-if.<br />

000500*<br />

000510 Finish-Pos.<br />

000520*<br />

000530* Release the resource obtained by the <strong>SAF</strong> subroutine<br />

000540 call "COBW3_FREE” using COBW3.<br />

000550*<br />

000560 SafSample1-End.<br />

000570*<br />

000580 exit program.<br />

000590*<br />

000600 outputContinuousScreenProc section.<br />

000610* Registration of various conversion data<br />

000620* Get the Cookie data <strong>for</strong> AccessCounter<br />

000630 compute AccessCounter = function NUMVAL(COBW3-COOKIE-VALUE).<br />

000640 add 1 to AccessCounter.<br />

000650 move AccessCounter to COBW3-COOKIE-VALUE.<br />

000660 move zero to COBW3-COOKIE-VALUE-LENGTH.<br />

000670*


92 Chapter 6. Samples<br />

000680* The access counter value is registered in conversion data.<br />

000690 per<strong>for</strong>m entryAccessCounterProc.<br />

000700 move “Access Count” to COBW3-CNV-NAME.<br />

000710 move AccessCounter to COBW3-CNV-VALUE.<br />

000720 per<strong>for</strong>m entryConversionDataProc.<br />

000730*<br />

000740* Get and register remote hostname.<br />

000750 set COBW3-REMOTE-HOST to true.<br />

000760 call "COBW3_GET_REQUEST_INFO" using COBW3.<br />

000770 if program-status not = zero then<br />

000780 move "<strong>SAF</strong>ERROR.htm" to HTMLFilename<br />

000790 per<strong>for</strong>m outputScreenProc<br />

000800 go to Finish-Pos<br />

000810 end-if.<br />

000820 move “Hostname” to COBW3-CNV-NAME.<br />

000830 move COBW3-REQUEST-INFO to COBW3-CNV-VALUE.<br />

000840 per<strong>for</strong>m entryConversionDataProc.<br />

000850*<br />

000860* Get and register the browser name.<br />

000870 move "User-Agent" to COBW3-HEADER-NAME.<br />

000880 call "COBW3_RECEIVE_HEADER" using COBW3.<br />

000890 if program-status not = zero then<br />

000900 move <strong>SAF</strong>ERROR.htm" to HTMLFilename<br />

000910 per<strong>for</strong>m outputscreenProc<br />

000920 go to Finish-Pos<br />

000930 end-if.<br />

000940 move “Browser Name” to COBW3-CNV-NAME.<br />

000950 move COBW3-HEADER-VALUE to COBW3-CNV-VALUE.<br />

000960 per<strong>for</strong>m entryConversionDataProc.<br />

000970*<br />

000980* Output the prototype HTML file.<br />

000990 move "<strong>SAF</strong>RPLY2.htm" to HTMLFilename.<br />

001000 per<strong>for</strong>m outputscreenProc.<br />

001010*<br />

001020 outputContinuousScreenProc-End.<br />

001030 exit<br />

001040*<br />

001050*<br />

001060 entryAccessCounterProc section.<br />

001070* After the browser exists the content of the access counter can be<br />

retained by setting<br />

001080* an expiration. However, if the browser is different, it is not<br />

significant.<br />

001090 call "COBW3_SET_COOKIE" using COBW3.<br />

001100 if program-status not = zero then<br />

001110 move "<strong>SAF</strong>ERROR.htm" to HTMLFilename<br />

001120 per<strong>for</strong>m outputScreenProc<br />

001130 go to Finish-Pos<br />

001140 end-if.<br />

001150 entryAccessCounterProc-End.<br />

001160 exit.<br />

001170*<br />

001180 entryConversionDataProc section.<br />

001190 call "COBW3_SET_CNV" using COBW3.<br />

001200 if program-status not = zero then<br />

001210 move '<strong>SAF</strong>ERROR.htm" to HTMLFilename<br />

001220 per<strong>for</strong>m outputScreenProc<br />

001230 go to Finish-Pos<br />

001240 end-if.<br />

001250 entryConversionDataProc-End.<br />

001260 exit.<br />

001270*<br />

001280 outputScreenProc section.<br />

001290* Get the physical path of the application and<br />

001300* edit the HTML document name.<br />

001310 if pathName = space then<br />

001320 per<strong>for</strong>m getPhysicalPath<br />

001330 end-if.<br />

001340 move space to COBW3-HTML-FILENAME.<br />

001350 move pathName(1:pathSize) to COBW3-HTML-FILENAME.


Chapter 6. Samples 93<br />

001360 compute copyStartPos = pathSize + 1.<br />

001370 move "\" to COBW3-HTML-FILENAME(copyStartPos:1).<br />

001380 compute copyStartPos = copyStartPos +1.<br />

001390 compute leftLength = 256 – copyStartPos.<br />

001400 move HTMLFilename to COBW3-HTML-FILENAME(copyStartPos:256).<br />

001410*<br />

001420* Output HTML document.<br />

001430 call "COBW3_PUT_HTML" using COBW3.<br />

001440*<br />

001450 outputScreenProc-End.<br />

001460 exit.<br />

001470*<br />

001480 getPhysicalPath section.<br />

001490 move space to pathName.<br />

001500 set COBW3-PHYSICALPATH to true.<br />

001510 call "COBW3_GET_REQUEST_INFO" using COBW3.<br />

001520 if COBW3-STATUS = zero then<br />

001530 move COBW3-REQUEST-INFO to pahtName<br />

001540 move COBW3-REQUEST-INFO-LENGTH to pahtSize<br />

001550 end-if.<br />

001560*<br />

001570 getPhysicalPath-End.<br />

001580 exit.<br />

This sample program per<strong>for</strong>ms the following<br />

processing.<br />

• Get the Cookie data sent from the WWW browser.<br />

• Register the Cookie data.<br />

• Output the Web page <strong>for</strong> processing result.<br />

Select the output Web page<br />

according to the Cookie data contents. Register the<br />

conversion data and edit the output Web page<br />

if necessary.<br />

The following diagram shows the progress of the transaction:<br />

WWW Browser<br />

<strong>SAF</strong>START.htm<br />

WWW Browser<br />

<strong>SAF</strong>RPLY1.htm<br />

WWW Browser<br />

<strong>SAF</strong>RPLY2.htm<br />

Only the first<br />

time<br />

<strong>SAF</strong>SMPL1.dll<br />

Repeats after<br />

the first time<br />

The following outlines the purpose and application of each function.


94 Chapter 6. Samples<br />

Getting Cookie Data<br />

Thi s sample uses a Cookie name of “Your access counter.” To get the Cookie data,<br />

enter this Cookie name in the COBW3-COOKIE-NAME and call<br />

“COBW3_GET_COOKIE” (lines 370 to 380).<br />

This sample uses the Cookie data to detect the first access (from “<strong>SAF</strong>START.htm”)<br />

and to hold the access count data. There is no Cookie data in the first access.<br />

There<strong>for</strong>e, the Cookie data is not found when COBW3_GET_COOKIE is called. In<br />

such case, initial processing is executed (lines 4 20 to 460).<br />

In the second or subsequent access, the Cookie data is always sent (lines 470 to<br />

480). The counter is set to one (1) during initial processing, and it is incremented by<br />

1 during subsequent processing.<br />

Registering Cookie Data<br />

Set the desired Cookie name in the COBW3-COOKIE-NAME, and set its contents in<br />

the COBW3-COOKIE-VALUE. Then, call COBW3_SET_COOKIE. The registered<br />

Cookie data is sent to the WWW browser during HTML file output.


Getting Request In<strong>for</strong>mation<br />

Chapter 6. Samples 95<br />

To get the request in<strong>for</strong>mation, set the condition name of the desired in<strong>for</strong>mation<br />

and call COBW3_GET_REQUEST_INFO. After getting the request in<strong>for</strong>mation, the<br />

in<strong>for</strong>mation will be in COBW3-REQUEST-INFO.<br />

This sample gets two sets of request in<strong>for</strong>mation. One is the physical path<br />

in<strong>for</strong>mation of the virtual path. It is used to determine the path name of output Web<br />

page which is stored in the same path as the application (<strong>SAF</strong>SMPL1.dll). (See lines<br />

1490 to 1550.)<br />

As the current directory is insufficient <strong>for</strong> applications locating under NES control, the<br />

path name must be determined based on this in<strong>for</strong>mation. Otherwise, the absolute<br />

path must be specified. The second in<strong>for</strong>mation request gets the host name where<br />

the WWW browser is running (lines 750 to 810). It is displayed on the screen.<br />

Getting Header In<strong>for</strong>mation<br />

To get the header in<strong>for</strong>mation, set the desired HTTP header name in COBW3-<br />

HEADER-NAME and call COBW3_RECEIVE_HEADER. After getting the http header<br />

in<strong>for</strong>mation, the header in<strong>for</strong>mation will be in the COBW3-HEADER-VALUE.<br />

This sample uses the header to get the WWW browser in<strong>for</strong>mation to be displayed<br />

on the screen. The WWW browser in<strong>for</strong>mation can be obtained from the “User-<br />

Agent” header (lines 870 to 930).


96 Chapter 6. Samples


Appendix A. Frequently Asked Questions<br />

The following are answers to typical questions about the use of <strong>SAF</strong> subroutines.<br />

Q1.<br />

Why is an error message displayed by the WWW browser?<br />

A1.<br />

Check the following points.<br />

•<br />

•<br />

The MIME type you have set <strong>for</strong> WWW server setup and <strong>for</strong> Web application<br />

startup by “obj.conf” must match the MIME type that corresponds to the<br />

extension written in the FORM tag (ACTION) of HTML document.<br />

The WWW server setup, the program name, and the HTML document storage<br />

location must be correct. Also, the compiler options must be correct.<br />

Q2.<br />

Is it necessary to protect data from external access?<br />

A2.<br />

Data may be read or modified by an unauthorized person during communication<br />

between client and server. We recommend to use appropriate security such as<br />

Secure Socket Layer (SSL) to protect data from unauthorized access. Consult to the<br />

server manager or administrator.<br />

Q3.<br />

File I/O of a Web application is incorrect.<br />

A3.<br />

Each user must be authorized to read/write files when executing a Web application<br />

that does file I/O.<br />

Q4.<br />

How can I change the display dynamically in a Web application?<br />

A4.<br />

1. Use the COBW3_SET_CNV_XX or others.<br />

Write the “//COBOL//conversion-name//COBOL//” in the variable section of the<br />

Web page <strong>for</strong> processing result output. Register a character string (a conversion<br />

character string) to be converted by the conversion name using the<br />

COBW3_SET_CNV_XX or others, and convert it into the conversion character<br />

string by the COBW3_PUT_HTML. This can change the page dynamically.<br />

2. Use the COBW3_PUT_TEXT.<br />

Usually, data stored in an output file such as HTML document can be written by<br />

COBW3_PUT_TEXT.


98 Appendix A. Frequently Asked Questions<br />

Prepare the data of COBW3_PUT_TEXT <strong>for</strong> each of program conditions, and<br />

specify the desired data name in the COBW3_PUT_TEXT. This can change the<br />

page dynamically.<br />

3. Divide a single page into two or more files.<br />

An output file can be divided into two or more files.<br />

Prepare several files which write the second half of the page in the desired<br />

<strong>for</strong>mat. Call COBW3_PUT_HTML, specifying a file name that identifies the first<br />

half of output page. Then change the output file name according to the program<br />

conditions, and call the COBW3_PUT_HTML again.<br />

You can also change the second half of the page dynamically eliminating the<br />

preparation of multiple similar files. Also, you can create pages to satisfy various<br />

situations by combination of solutions (1) to (3).<br />

Q5.<br />

Why does the Web application not operate after its startup?<br />

A5.<br />

Make sure that you have specified “COBW3_INIT” at the beginning of the Web<br />

application.<br />

If OK, collect the error in<strong>for</strong>mation or debug the program by referring to Chapter 5<br />

“Debugging a <strong>SAF</strong> Application.”<br />

Q6.<br />

Why does the following message appear?<br />

“Server Error<br />

The server encountered an internal error or mis-configuration and was unable to<br />

complete your request.”<br />

The specified Web application returns only a part of Web header.<br />

A6.<br />

The “Content-type” may be incorrect. Review the COBW3-CONTENT-TYPE value you<br />

have specified in the COBW3_PUT_HEAD.<br />

1. To output an HTML document:<br />

Do not call COBW3_PUT_HEAD, omit the COBW3-CONTENT-TYPE value (LOW-<br />

VALUE), or call COBW3_PUT_HEAD by specifying COBW3-CONTENT-TYPE-HTML.<br />

2. To output text data:<br />

Call COBW3_PUT_HEAD by specifying COBW3-CONTENT-TYPE-TEXT.


Appendix A. Frequently Asked Questions 99<br />

Q7.<br />

Why does the WWW browser display the “Content-type” declaration?<br />

A7.<br />

If the COBW3-DMODE-DBG is specified in COBW3_INIT, the “Content-type” and<br />

other header in<strong>for</strong>mation is displayed by the WWW browser as debug in<strong>for</strong>mation.<br />

It is not displayed if COBW3-DMODE is not specified.<br />

Q8.<br />

Why does the message of the file download appear when I execute the Web<br />

application?<br />

A8.<br />

This type of message may be output if the “Content-type” declaration is incorrect in<br />

the Web application. Check the “Content-type” declaration <strong>for</strong> an error.<br />

Q9.<br />

Do you have any caution when writing a COBOL program during creation of Web<br />

application?<br />

A9.<br />

You can use almost all COBOL functions directly in a Web application. However, you<br />

cannot use the following screen operation functions.<br />

•<br />

•<br />

•<br />

Presentation file module (screen handling module)<br />

Screen handling module.<br />

ACCEPT/DISPLAY function (However, you can use the environment variables and<br />

date and time control functions.)<br />

For details of Web parameter reception, reference, and process result output, see<br />

Chapter 3 “How To Use <strong>SAF</strong> <strong>Subroutines</strong>.”<br />

Q10.<br />

How can I set up environment variables required <strong>for</strong> WWW server startup?<br />

A10.<br />

Add the required environment variables to the environment setup file, and specify<br />

the environment setup file name in the “env” parameter of the line where<br />

“COBOL_Init” is set in the “obj.conf” file. Then, restart the NES.<br />

Otherwise, store the initialization file <strong>for</strong> execution (COBOL85.CBR) which defines the<br />

required environment in<strong>for</strong>mation in the same folder as the Web application (.dll).


100 Appendix A. Frequently Asked Questions<br />

Q11.<br />

Is it impossible to use a COBOL debugger?<br />

A11.<br />

You can use a COBOL debugger in the Web environment. See”Checking Execution<br />

Using the Interactive Debugger” in Chapter5.<br />

Q12.<br />

The “Status-code” is displayed by the WWW browser. What does it mean?<br />

A12.<br />

Refer to Appendix A of “Web Linkage <strong>Guide</strong>.”<br />

Q13.<br />

Can I control the timeout period while the Web application returns the browser the<br />

processing result?<br />

A13.<br />

This is a WWW server function. Refer to the “WWW server manuals”.<br />

Q14.<br />

Can I use an HTML document having frames in a Web application?<br />

A14.<br />

You need not specify special setup or processing of frame functions in the Web<br />

application. You can use the frames in an HTML document if the WWW browser<br />

supports frame functions.<br />

Q15.<br />

Why is the VALUE not searched correctly if the tag is set in the<br />

COBW3_CHECK_VALUE, etc?<br />

A15.<br />

If the NAME is omitted in the INPUT tag, the WWW browser may not enter the<br />

INPUT tag VALUE in the Web data area. Always specify the NAME in the INPUT tag<br />

if the VALUE is required.<br />

Q16.<br />

Why is a Web parameter not searched correctly if COBW3_GET_VALUE or<br />

COBW3_CHECK_VALUE is set?<br />

A16.<br />

If the length of search character string exceeds the limit in the Web parameter, it is<br />

truncated by the <strong>SAF</strong> subroutine. There<strong>for</strong>e, you may not have the expected result.


Appendix A. Frequently Asked Questions 101<br />

Q17.<br />

Why does access to a file fail when I specify its absolute path?<br />

A17.<br />

Specify the COBOL file storage location according to the drive configuration of the<br />

server machine you use when you use the file during execution of Web application.<br />

Q18.<br />

Why is error message “The document has no data at all” displayed by the WWW<br />

browser?<br />

A18.<br />

Always insert a linefeed be<strong>for</strong>e the tag of a Web page that is output by the<br />

<strong>SAF</strong> COBOL Web application.<br />

Example:<br />

↓<br />

↓<br />

...<br />

↓<br />

↓<br />

↓<br />

...<br />

↓<br />

↓<br />

Q19.<br />

The COBOL debugger has started but no debugging starts.<br />

A19.<br />

Make sure that [Debugging in<strong>for</strong>mation file storage folders] has been set correctly in<br />

the [Debugging In<strong>for</strong>mation] page of [Start Debugging] dialog.<br />

Q20.<br />

Why is an incorrect value collected by the <strong>SAF</strong> subroutine?<br />

A20.<br />

If the extension path is set in the request URL, the following invalid values may be<br />

collected.<br />

• COBW3-URL: URL of request<br />

• COBW3-URI: URI of request<br />

• COBW3-MIMETYPE: MIME type of request<br />

• COBW3-VIRTUALPATH: Virtual path of request<br />

• COBW3-PHYSICALPATH: Physical path corresponding to the request virtual path<br />

• A value collected by COBW3_<strong>SAF</strong>_GET_BASENAME


102 Appendix A. Frequently Asked Questions<br />

Q21.<br />

Why does error message “No F3BIPRCT.DLL is found” appear on the server?<br />

A21.<br />

Make sure that the COBOL run-time system has been installed correctly. The USER<br />

environment variables you have set are invalid <strong>for</strong> the operation of Web applications.<br />

First, place the name of the COBOL run-time system install folder in the PATH<br />

environment variable of the server machine. You must restart the system to validate<br />

the system environment variables.<br />

Q22.<br />

Why does the access to network environment resources fail?<br />

A22.<br />

The network drive configuration may not be valid <strong>for</strong> the Web application when you<br />

log in.<br />

Specify the UNC during access to the resources of network environment that you use<br />

during application execution. For details, refer to “Fujitsu COBOL User’s <strong>Guide</strong>” in<br />

Chapter 21.<br />

Q23.<br />

What can I do if the server does not respond?<br />

A23.<br />

The server may be waiting <strong>for</strong> an input in a window or a message box.<br />

When executing a COBOL program on the Web server, write the following<br />

environment variable in<strong>for</strong>mation in the initialization file <strong>for</strong> execution or set the<br />

in<strong>for</strong>mation in the system environment variables.<br />

If you have specified the environment variable in<strong>for</strong>mation, the windows and<br />

message boxes are not displayed and you can avoid an operator input wait status.<br />

Environment variable in<strong>for</strong>mation Meaning<br />

@MessOutFile=file-name When the COBOL program is executed, its<br />

messages are output to the specified file.<br />

@WinCloseMsg=OFF The window closing message is not displayed.<br />

For details of the environment variable in<strong>for</strong>mation, refer to the “Fujitsu COBOL<br />

User’s <strong>Guide</strong>.”<br />

Also, do not use the following window display functions from the COBOL program.<br />

• Presentation file module (Screen handling module)<br />

• Screen handling module<br />

• ACCEPT/DISPLAY function (However, you can use the environment variables and<br />

date and time control functions.)<br />

For more in<strong>for</strong>mation, refer to Subsection 23.1.3 of “Fujitsu COBOL User’s <strong>Guide</strong>.”


Appendix A. Frequently Asked Questions 103<br />

In addition, you may have incorrect NES and ODBS setup (if you are using the<br />

ODBC). Check them <strong>for</strong> an error.<br />

Q24.<br />

Why does COBOL debugger not start?<br />

A24.<br />

Check the following points:<br />

• The @CBR_ATTACH_TOOL=TEST environment variable in<strong>for</strong>mation must be set.<br />

• The COBOL Tool Attaching Service must have started.<br />

Q25.<br />

Is it better to back up the “obj.conf” file be<strong>for</strong>e changing it?<br />

A25.<br />

We recommend to have a backup of “obj.conf” file as you may fail to restart your<br />

NES after your modification.<br />

Q26.<br />

If the Web application that uses session management functions is started twice, it<br />

may not operate correctly.<br />

A26.<br />

The operation of such Web application is unstable if started twice. To avoid this<br />

problem, use Java script on the WWW browser to prevent duplicate application<br />

startup. For general notes on WWW browser operations, refer to Appendix A of<br />

“Web Link <strong>Guide</strong>.”


104 Appendix A. Frequently Asked Questions


Appendix B. Error Recovery Processing<br />

If an error is detected while a <strong>SAF</strong> subroutine is being executed, the <strong>SAF</strong> subroutine<br />

executes error recovery processing.<br />

An error message is output in the following <strong>for</strong>mat:<br />

COB message No.: COBW3: Message text<br />

• COB message No.: The serial number of the message is displayed.<br />

• Message text: The error detail is displayed.<br />

The displayed error content is also output to the log file if logging of <strong>SAF</strong> subroutines<br />

is enabled.<br />

The message numbers and message texts displayed are shown below.<br />

Message Message text<br />

number<br />

00100 The Processing was not able to be continued. Because, the value was not set<br />

in COBW3-CONTEXT.<br />

01100 It is thought that the work area or the object was destroyed. Check the<br />

object of the Web subroutine and the usage of the area.<br />

01500 The Web subroutine cannot operate correctly in the calling COBOL application<br />

operation code system.<br />

01501 The operation state of the calling application is abnormal. The Web<br />

subroutine cannot operate normally.<br />

02050 Search character string length specified as a negative value. The processing<br />

continues as if 0 was specified.<br />

02051 A value was specified that exceeds the limit <strong>for</strong> the character string length of<br />

the search string. The processing continues assuming that the maximum<br />

length was specified.<br />

03000 Web application was called by a method without GET or POST.<br />

03001 COBW3_INIT was called two times or more. Please call COBW3_FREE a<br />

second time be<strong>for</strong>e the call.<br />

03002 The work area of the Web subroutine could not be acquired.<br />

03020 The data that was passed by POST or GET was not acquired successfully.<br />

03030 Failed in the acquisition of the work area of the Web subroutine.<br />

03040 Uploaded file in<strong>for</strong>mation could not be acquired.<br />

03041 The Web parameter can't be processed because failed to acquire header<br />

in<strong>for</strong>mation.<br />

03042 multipart/<strong>for</strong>m-data is specified <strong>for</strong> ENCTYPE of the FORM tag though the<br />

method is things except POST. The Web parameter and uploaded file<br />

in<strong>for</strong>mation could not be acquired.<br />

03045 An error in processing the output to the browser.<br />

03065 Environment variable @CBR_WEB_OUT_CODE was set incorrectly. It is<br />

assumed that the conversion code was not set<br />

03200 Conversion from UTF-8 to UCS-2 failed.


106 Appendix B. Error Recovery Processing<br />

03201 Conversion from UCS-2 to UTF-8 failed.<br />

03700 A code was specified that could not be recognized as a character. Processing<br />

continues.<br />

03701 EUC and SJIS character strings are intermingled. Processing continues.<br />

03850 Cookie was not acquired successfully.<br />

04000 There is no Web parameter.<br />

04001 The Web parameter length is 0.<br />

04006 A negative value or “0” was specified <strong>for</strong> COBW3-NUMBER. The processing<br />

continues as if 1 was specified.<br />

04008 The length of VALUE data exceeds the limit. The string is truncated to the<br />

supported length.<br />

04009 The data passed with POST or GET method was nothing.<br />

04400 The conversion name is not specified. Please set the conversion name.<br />

04401 A negative value was specified <strong>for</strong> character string length of the conversion<br />

name. The processing continues as if 0 was specified.<br />

04402 A value was specified that exceeds the limit <strong>for</strong> character string length of the<br />

conversion name. The processing continues assuming the maximum length<br />

was specified.<br />

04450 Failed to delete the variable name specified in COBW3-CNV-NAME because it<br />

could not be found in the registered in<strong>for</strong>mation.<br />

04470 Failed to change the variable name specified in COBW3-CNV-NAME because it<br />

could not be found in the registered in<strong>for</strong>mation.<br />

04480 Failed to delete the variable name specified in COBW3-CNV-NAME.<br />

05000 Failed in the execution of the system command.<br />

05001 The system command is not specified.<br />

05500 The file name is not specified. Please set the file name.<br />

05501 There is no uploaded file in<strong>for</strong>mation.<br />

05510 Failed to acquire the path name in the client of the uploaded file.<br />

05511 The character string length of the path name in the client of the uploaded file<br />

exceeded the limitation. The string is truncated to the supported length.<br />

05520 Failed to acquire the file name in the client of the uploaded file.<br />

05521 The character string length of the file name in the client of the uploaded file<br />

exceeded the limitation. The string is truncated to the supported length.<br />

05530 Failed to acquire the content type of the uploaded file.<br />

05531 The character string length of the content type of the uploaded file exceeded<br />

the limitation. The string is truncated to the supported length.<br />

05550 The file was not generated because the specified file name had already<br />

existed.<br />

05551 Failed to generate the file.<br />

05552 Failed to generate data in the subroutine. The generated file can't be deleted<br />

with COBW3_DEL_UPLOADEDFILE.<br />

05580 The specified file name is not a file generated in the same thread. The file was<br />

not deleted.<br />

05581 Failed to delete the specified file.<br />

06100 An I-O error occurred in the OPEN process of the specified HTML document<br />

file.


Appendix B. Error Recovery Processing 107<br />

06101 An I-O error occurred in the READ process of the specified HTML document<br />

file.<br />

06102 The length of the specified HTML document file is 0.<br />

06105 A conversion name in the HTML document was not registered using<br />

COBW3_CNV_SET. Please register the conversion data using<br />

COBW3_CNV_SET.<br />

06106 Failed in the output because the output work area of the HTML document was<br />

insufficient. Please confirm the conversion data length corresponding to the<br />

conversion name.<br />

06107 Failed in the output because an error was found in the specified <strong>for</strong>m of the<br />

conversion name within the HTML document.<br />

06108 The string length of the specified conversion name is too long. Check the<br />

conversion name.<br />

06120 Failed to output the HTML document to the WWW server.<br />

06130 The number of characters in one line of the HTML document exceeds the limit.<br />

The string is truncated to the supported length.<br />

06300 The conversion name is not specified. Please set the conversion name.<br />

06301 A negative value was specified <strong>for</strong> character string length of the conversion<br />

name. The processing is continued regarding <strong>for</strong> 0 to have been specified.<br />

06302 A value was specified that exceeds the limit <strong>for</strong> character string length of the<br />

conversion name. The processing continues assuming the maximum length<br />

was specified.<br />

06303 The conversion character string is not specified. Please confirm the<br />

conversion character string.<br />

06304 A negative value was specified <strong>for</strong> character string length of the conversion<br />

character string. The processing continues assuming 0 was specified.<br />

06305 A value was specified that exceeds the limit <strong>for</strong> character string length of the<br />

conversion character string. The processing continues assuming the maximum<br />

length was specified.<br />

06310 The specified variable name has already been registered. The old conversion<br />

in<strong>for</strong>mation remains effective.<br />

06320 Failed in registration because the registration work area <strong>for</strong> the conversion<br />

in<strong>for</strong>mation was insufficient. Please register again after calling<br />

COBW3_CNV_INIT and initializing conversion in<strong>for</strong>mation.<br />

06330 Failed to delete conversion in<strong>for</strong>mation.<br />

06502 Unexpected error occurred in writing data on standard output.<br />

06503 A negative value was specified <strong>for</strong> the length of the string to be output. The<br />

processing continues assuming 0 was specified.<br />

06504 A value was specified that exceeds the limit <strong>for</strong> output character string length.<br />

The processing continues assuming the maximum length was specified.<br />

06700 COBW3_PUT_HTML or COBW3_PUT_TEXT has already been called. The<br />

output request <strong>for</strong> the header is invalid.<br />

06702 COBW3-PUT-HEAD contains no colon (:). The specified COBW3-PUT-HEAD is<br />

ignored.<br />

06704 A negative value was specified <strong>for</strong> COBW3-PUT-HEAD-LENGTH. The<br />

processing continues assuming 0 was specified.<br />

06706 A value was specified that exceeded the limit <strong>for</strong> COBW3-PUT-HEAD-LENGTH.<br />

The processing continues assuming the maximum length was specified.<br />

06708 The object output as a header was not specified.


108 Appendix B. Error Recovery Processing<br />

06710 A value that had already been output and a different value were specified <strong>for</strong><br />

COBW3-CONTENT-TYPE.<br />

06714 A value that had already been output and a different value were specified <strong>for</strong><br />

COBW3-STATUS-CODE.<br />

06730 An error not anticipated in the declaration of Content-type occurred.<br />

06734 An error not anticipated in the declaration of Status-code occurred.<br />

06736 Unexpected error occurred in declaration of specified header.<br />

06742 Failed in the output of the specified header.<br />

06746 The output of the header could not be completed.<br />

07010 The user name was not able to be acquired.<br />

07011 The character string length of the user name exceededthe limitation. The<br />

maximum length is made effective.<br />

07020 The password was not able to be acquired.<br />

07021 The character string length of the password exceeded the limitation. The<br />

maximum length is made effective.<br />

07030 The IP address was not able to be acquired.<br />

07031 The character string length of the IP address exceeded the limitation. The<br />

maximum length is made effective..<br />

07040 The authentication type was not able to be acquired.<br />

07041 The character string length of the authentication type exceeded the limitation.<br />

The maximum is made effective.<br />

07500 Session not started.<br />

07510 Unable to start a session because COBW3_PUT_HTML or COBW3_PUT_TEXT<br />

already invoked.<br />

07520 Unable to end a session because COBW3_PUT_HTML or COBW3_PUT_TEXT<br />

already invoked.<br />

07558 Unable to start the timeout monitoring.<br />

07562 Failure in the timeout monitoring <strong>for</strong> some reason.<br />

07566 Failure in interrupting the timeout monitoring.<br />

07570 Unable to prepare <strong>for</strong> the timeout monitoring <strong>for</strong> some reason. Unable to start<br />

a session.<br />

07580 Unable to interrupt the timeout processing.<br />

07584 Incorrect session ID got from Cookie data.<br />

07588 Failure in getting the session in<strong>for</strong>mation management area.<br />

07590 Failure in executing the timeout monitoring.<br />

07600 Session already started.<br />

07602 Unable to start a session because the timeout time is specified as 0.<br />

07604 Value exceeding the restriction specified <strong>for</strong> the timeout time. The processing<br />

is continued assuming that the maximum length is specified.<br />

07606 Unable to start a session because an invalid value is specified in the session<br />

data type.<br />

07608 Unable to start a session because of a failure in creating Cookie data <strong>for</strong> the<br />

session.<br />

07610 Unable to register session data because 0 was specified <strong>for</strong> the session data<br />

size.


Appendix B. Error Recovery Processing 109<br />

07614 Value exceeding the restriction specified <strong>for</strong> the session data size. The<br />

processing is continued assuming that the maximum length is specified.<br />

07618 Incorrect object specified <strong>for</strong> the session data.<br />

07650 Unable to get session data because a mismatch exists between the specified<br />

and registered session data sizes.<br />

07660 Unable to get session data because a value other than null is set in the<br />

session data.<br />

07670 No session data registered.<br />

07680 Unable to change the timeout time because 0 was specified <strong>for</strong> the timeout<br />

time.<br />

08004 A negative value was specified <strong>for</strong> COBW3-HEADER-NAME-LENGTH. The<br />

processing continues assuming 0 was specified.<br />

08005 The script-name could not be acquired.<br />

08006 A value was specified that exceeded the limit <strong>for</strong> COBW3-HEADER-NAME-<br />

LENGTH. The processing continues assuming the maximum length was<br />

specified.<br />

08008 COBW3-HEADER-NAME is not specified.<br />

08010 Failed to acquire the HTTP header.<br />

08020 The length of COBW3_HEADER_VALUE exceeds the limit. The string is<br />

truncated to the supported length.<br />

08024 The HTTP header specified <strong>for</strong> COBW3_HEADER_NAME could not be found.<br />

08030 The character string length of the script-name exceeds the limit. The<br />

maximum length is used.<br />

08500 COBW3_PUT_HTML or COBW3_PUT_TEXT has already been called. Operation<br />

to cookie is invalid.<br />

08510 The cookie name is not specified. Set the cookie name.<br />

08512 A negative value was specified <strong>for</strong> the string length of the cookie name. The<br />

processing continues assuming 0 was specified.<br />

08514 A value was specified that exceeded the limit <strong>for</strong> the string length of the<br />

cookie name. The processing continues assuming the maximum length was<br />

specified.<br />

08520 The cookie value is not specified. Set the cookie value.<br />

08522 A negative value was specified <strong>for</strong> the string length of the cookie value. The<br />

processing continues assuming 0 was specified.<br />

08524 A value was specified that exceeded the limit <strong>for</strong> the string length of the<br />

cookie value. The processing continues assuming the maximum length was<br />

specified.<br />

08530 Failed to change the specified cookie data because it was not registered.<br />

08532 The specified cookie name has already been registered. The old cookie data<br />

remains effective.<br />

08540 A date be<strong>for</strong>e Oct 15, 1582 is not valid as a cookie period. The period is<br />

assumed not to have been specified.<br />

08541 The year <strong>for</strong> the cookie period is not specified correctly. The period is<br />

assumed not to have been specified.<br />

08542 The month <strong>for</strong> the cookie period is not specified correctly. The period is<br />

assumed not to have been specified.<br />

08543 The day <strong>for</strong> the cookie period is not specified correctly. The period is<br />

assumed not to have been specified.


110 Appendix B. Error Recovery Processing<br />

08544 The hour <strong>for</strong> the cookie period is not specified correctly. The period is<br />

assumed not to have been specified.<br />

08545 The minute <strong>for</strong> the cookie period is not specified correctly. The period is<br />

assumed not to have been specified.<br />

08546 The second <strong>for</strong> the cookie period is not specified correctly. The period is<br />

assumed not to have been specified.<br />

08550 An invalid value was specified <strong>for</strong> the cookie security. The security is assumed<br />

not to have been specified.<br />

08560 An invalid value was specified <strong>for</strong> the cookie registration type. The<br />

registration type is assumed not to have been specified.<br />

08570 Failed in registration because the registration work area <strong>for</strong> the cookie data<br />

was insufficient. Please register again after calling COBW3 _INIT_COOKIE to<br />

initialize conversion in<strong>for</strong>mation.<br />

08580 Failed to encode Cookie data.<br />

08610 Failed to delete the specified cookie data because it was not registered.<br />

08620 Failed to delete the specified cookie data.<br />

08710 An invalid value was specified <strong>for</strong> the initialization type of cookie in<strong>for</strong>mation.<br />

The initialization type is assumed not to have been specified.<br />

08720 Failed in initialization of the request data by cookie in<strong>for</strong>mation because the<br />

registration work area <strong>for</strong> the cookie in<strong>for</strong>mation was insufficient.<br />

08810 The length of the cookie value exceeded the limit. The string is truncated to<br />

the supported length.<br />

08820 Cookie data was not sent from the client.<br />

09001 The correct value is not specified <strong>for</strong> COBW3_REQUEST_INFO_TYPE.<br />

09010 Failed to acquire the request.<br />

09020 The length of COBW3_REQUEST_INFO exceeded the limit. The string is<br />

truncated to the supported length.<br />

09500 COBW3_CNV_SET can't be used in the Unicode environment.<br />

09501 COBW3_CNV_DEL can't be used in the Unicode environment.<br />

09502 COBW3_NAME can't be used in the Unicode environment.<br />

09504 COBW3_VALUE can't be used in the Unicode environment.<br />

09520 This subroutine can't be used in the ASCII environment.<br />

20000 Failed to load the COBOL application.<br />

20001 The specified environment setting file does not exist.<br />

20002 No COBOL application to be executed is specified.<br />

20003 Failed to acquire the start address of the COBOL application processing to be<br />

executed.<br />

20004 An error of unknown origin occurs in the director.<br />

20005 Environment setting ends abnormally in the director.<br />

20006 Failed in memory allocation.<br />

20007 Environment setting descriptions are erroneous.<br />

20008 The environment setting file name is incorrect.<br />

20009 No COBOL application to be freed is specified.<br />

21000 COBW3-<strong>SAF</strong>-CONTEXT is not set.


Appendix B. Error Recovery Processing 111<br />

21100 No character string is set in COBW3-<strong>SAF</strong>-PARM-NAME or COBW3-<strong>SAF</strong>-PARM-<br />

NAMEN.<br />

21102 A negative value is set in COBW3-<strong>SAF</strong>-PARM-NAME-LENGTH. The Web<br />

application regards the value as 0 and continues processing.<br />

21104 A value over the limit is set in COBW3-<strong>SAF</strong>-PARM-NAME-LENGTH. The Web<br />

application regards the value as the maximum value and continues<br />

processing.<br />

21106 COBW3-<strong>SAF</strong>-PARM-NAME could not be found.<br />

21110 Failed to acquire COBW3-<strong>SAF</strong>-PARM-VALUE.<br />

21112 The length of COBW3-<strong>SAF</strong>-PARM-VALUE exceeds the limit. The length up to<br />

the maximum length is valid.<br />

21210 Failed to acquire COBW3-<strong>SAF</strong>-BASENAME.<br />

21212 The length of COBW3-<strong>SAF</strong>-BASENAME exceeds the limit. The length up to the<br />

maximum length is valid.<br />

99999 Can’t open message catalog.


112 Appendix B. Error Recovery Processing


Appendix C. <strong>Architecture</strong> of a <strong>NetCOBOL</strong> <strong>SAF</strong><br />

Application<br />

Commodity subscription<br />

screen<br />

Unit price 200<br />

A 1<br />

Unit price 300<br />

B 3<br />

Unit price 100<br />

C 4<br />

Submit Cancel<br />

Confirmation screen<br />

Application data has been<br />

registered.<br />

Name Quantity Sum<br />

A 1 200<br />

B 3 900<br />

C 4 400<br />

Return<br />

NES<br />

<strong>SAF</strong><br />

Director<br />

IDENTIFICATION DIVISION.<br />

PROGRAM-ID. <strong>SAF</strong>MAIN01.<br />

ENVIRONMENT DIVISION.<br />

CONFIGURATION SECTION.<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

:<br />

LINKAGE SECTION.<br />

01 <strong>SAF</strong>CTX POINTER.<br />

PROCEDURE DIVISION USING <strong>SAF</strong>CTX.<br />

MOVE LOW-VALUE TO COBW3.<br />

SET COBW3-CONTEXT TO <strong>SAF</strong>CTX.<br />

*<br />

CALL "COBW3_INIT" USING COBW3.<br />

*Acquisition of data<br />

MOVE “PRICEA” TO COBW3-SEARCH-DATA.<br />

CALL “COBW3_GET_VALUE” USING COBW3.<br />

:<br />

*Registration of data<br />

MOVE “Quant i t y1” TO COBW3- CNV- NAME.<br />

MOVE O-QUANTITY1 TO COBW3-CNV-VALUE.<br />

CALL “COBW3_SET_CNV” USING COBW3.<br />

:<br />

*Setting path of result page<br />

SET COBW3-PHYSICAL-PATH TO TRUE.<br />

CALL "COBW3_GET_REQUEST_INFO" USING COBW3.<br />

MOVE SPACE TO COBW3-HTML-FILENAME..<br />

MOVE PATHNAME (1:PATHSIZE) TO<br />

COBW3-HTML-FILENAME.<br />

COMPUTE COPYSTARTPOS = PATHSIZE + 1.<br />

MOVE "/" TO<br />

COBW3-HTML-FILENAME (COPYSTARTPOS : 1).<br />

COMPUTE COPYSTARTPOS = COPYSTARTPOS+1.<br />

COMPUTE LEFTLENGTH = 256 – COPYSTARTPOS.<br />

MOVE HTMLFILENAME TO<br />

COBW3-HTML-FILENAME (COPYSTARTPOS : 256).<br />

*<br />

CALL "COBW3_PUT_HTML" USING COBW3.<br />

*<br />

CALL "COBW3_FREE" USING COBW3.<br />

*<br />

EXIT PROGRAM.<br />

…<br />

Application data has been<br />

registered.<br />

<br />

<br />

Name<br />

Quantity<br />

Sum<br />

<br />

<br />

A<br />

//COBOL//Quantity1//COBOL//<br />

//COBOL//Sum1//COBOL//<br />


114 Appendix C. <strong>Architecture</strong> of a <strong>NetCOBOL</strong> <strong>SAF</strong> Application


Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong><br />

Conversion <strong>Guide</strong><br />

The following describes how to convert Web applications using <strong>NetCOBOL</strong> CGI<br />

subroutines into Web applications using <strong>NetCOBOL</strong> <strong>SAF</strong> subroutines.


116 Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong><br />

Conversion from CGI to <strong>SAF</strong><br />

In principle, <strong>NetCOBOL</strong> <strong>SAF</strong> subroutines (hereafter referred to as <strong>SAF</strong> applications)<br />

guarantee upward compatibility in source <strong>for</strong> COBOL CGI applications (hereafter<br />

referred to as CGI applications). There<strong>for</strong>e, it is easy to modify Web applications<br />

created using CGI subroutines into Web applications using <strong>SAF</strong> subroutines.<br />

However, some modifications in the programs, compilations, and the linking methods<br />

are required, since the <strong>SAF</strong> subroutines have their own unique functions. This<br />

chapter describes the matters that require attention <strong>for</strong> the conversion from CGI to<br />

<strong>SAF</strong>.<br />

First, the table below shows the difference between Web applications created using<br />

CGI subroutines and Web applications using <strong>SAF</strong> subroutines.<br />

No. Item CGI applications <strong>SAF</strong> applications<br />

1 Application <strong>for</strong>m Main program (EXE) Subprogram (DLL)<br />

2 Unit of execution Process Thread<br />

3 Server interface area Unnecessary Inevitable<br />

4 Environment variable operation Arbitrary Restricted<br />

5 CGI environment variable Enabled using supplied Enabled using supplied<br />

operation<br />

subroutines or<br />

DISPLAY/ACCEPT<br />

statements.<br />

subroutines only.<br />

To implement a conversion from CGI to <strong>SAF</strong>, the above-noted items must be<br />

modified. Details of these modifications are described in the following chapters.<br />

The subroutines shown below only work in an environment where Web applications<br />

run in the ASCII code system, though they are included in the supplied <strong>NetCOBOL</strong><br />

<strong>SAF</strong> subroutines <strong>for</strong> the sake of compatibility.<br />

We recommend implementing corrections <strong>for</strong> the substitute subroutines, when<br />

per<strong>for</strong>ming a conversion from CGI to <strong>SAF</strong>.


Application Form<br />

Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong> 117<br />

Old Subroutine name New Substitute subroutine name<br />

COBW3_NAME<br />

COBW3_GET_VALUE<br />

COBW3_GET_VALUE_XX<br />

COBW3_GET_VALUE_NX<br />

COBW3_GET_VALUE_XN<br />

COBW3_GET_VALUE_NN<br />

COBW3_VALUE COBW3_CHECK_VALUE<br />

COBW3_CHECK_VALUE_X<br />

COBW3_CHECK_VALUE_N<br />

COBW3_CNV_SET COBW3_SET_CNV<br />

COBW3_SET_CNV_XX<br />

COBW3_SET_CNV_NX<br />

COBW3_SET_CNV_XN<br />

COBW3_SET_CNV_NN<br />

COBW3_CNV_DEL COBW3_DEL_CNV<br />

COBW3_DEL_CNV_X<br />

COBW3_DEL_CNV_N<br />

COBW3_CNV_INIT COBW3_INIT_CNV<br />

CGI applications and <strong>SAF</strong> applications have different executable <strong>for</strong>mats. CGI<br />

applications execute as a main EXE file, whereas <strong>SAF</strong> applications execute as<br />

subroutine in .DLL files. Thus, it is necessary to make alterations in the following<br />

manner:<br />

• Descriptions of the Web applications started on the Web page <strong>for</strong> invoking<br />

applications<br />

• Compilation and linking methods<br />

Web Pages <strong>for</strong> Invoking Applications<br />

Change the extension “.EXE” of the Web applications on the invoking Web page into<br />

the extension (MIME type) used by the applications on NES. Be<strong>for</strong>e changing the<br />

extension, it is necessary to correct the obj.conf file and to register the MIME type.<br />

For details, refer to the Chapter2 or Chapter3.<br />

For example, a CGI application "CGI.EXE" and a <strong>SAF</strong> application "<strong>SAF</strong>.DLL" should be<br />

changed as shown below.<br />

Web page <strong>for</strong> invoking the CGI applications<br />

<br />

...<br />


118 Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong><br />

Web page <strong>for</strong> invoking applications modified <strong>for</strong> <strong>SAF</strong> applications<br />

<br />

...<br />

<br />

Note: NES checks the extensions to identify applications. Thus, each application<br />

name need not be identical to the .DLL name, but will be the name of extension<br />

(MIME type) registered on NES.<br />

Compilation and Linking Methods<br />

Compilation Method<br />

In the case of CGI applications, there are no particular options <strong>for</strong> compiling<br />

programs. The only exception is the compilation option "MAIN", which the user has<br />

to set in the main program. On the contrary, the user must not set the compilation<br />

option "MAIN" in a <strong>SAF</strong> routine because each <strong>SAF</strong> application must be created in<br />

a.DLL <strong>for</strong>mat. In addition, <strong>SAF</strong> applications require the compilation option shown<br />

below. For details of the compilation option, refer to the "<strong>NetCOBOL</strong> <strong>User's</strong> <strong>Guide</strong>."<br />

• THREAD (MULTI)<br />

<strong>SAF</strong> applications are designed <strong>for</strong> multi-threaded operation. Set the compilation<br />

option THREAD (MULTI) in every source program.<br />

Linking Method<br />

In CGI applications, object files are linked to make .EXE files as shown below.<br />

LINK Main-program.obj F3BICIMP.lib LIBC.lib F3BICWSR.lib /OUT:<br />

Execution-<strong>for</strong>mat-name.exe<br />

<strong>SAF</strong> applications, however, must be created in .DLL <strong>for</strong>mat. In addition, linked the<br />

import library are different from CGI application program as follows.<br />

Unit of Execution<br />

LINK /DLL Initial-program.obj Work-program.obj End-program.obj<br />

F3BICBDM.obj F3BINSRT.lib F3BICIMP.lib KERNEL32.lib LIBC.LIB<br />

/OUT:Execution-<strong>for</strong>mat-name.dll /ENTRY:COBDMAIN<br />

Changing CGI applications into <strong>SAF</strong> applications means changing process-based<br />

applications into thread-based applications. The user should pay attention to the<br />

following:<br />

• Compilation method<br />

• Accessing common resources


Compilation Method<br />

Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong> 119<br />

It is necessary to set the compilation option THREAD (MULTI) <strong>for</strong> creating multithread<br />

objects.<br />

Accessing Common Resources<br />

A CGI application runs as one execution thread (single thread) in a dedicated process<br />

of the CGI application itself. Thus, there are no resources shared by several threads<br />

in a single process.<br />

A <strong>SAF</strong> application runs as several threads (multi-threads) within the process of NES<br />

itself. There<strong>for</strong>e, several threads may share resources.<br />

It is necessary to control synchronization in order to prevent competition when <strong>SAF</strong><br />

applications share common resources. Two types of synchronization controls are<br />

available <strong>for</strong> resource sharing: Automatic synchronization control by the COBOL runtime<br />

system, and synchronization control conducted by the <strong>SAF</strong> application itself<br />

using the "thread synchronization control subroutine" supplied by COBOL.<br />

For details, refer to the following sections in Chapter 24, Multithread Programs in the<br />

"<strong>NetCOBOL</strong> User’s <strong>Guide</strong>."<br />

• Resource Sharing among Threads<br />

• Thread Synchronization Control Subroutine<br />

Server Interface Area<br />

Users of CGI applications need not pay particular attention to the interface with the<br />

WWW server, with the exception of the environment variables. An <strong>SAF</strong> application is<br />

called by the <strong>NetCOBOL</strong> <strong>SAF</strong> director initiated by NES and receives an interface<br />

(parameter) area <strong>for</strong> transferring data with the <strong>NetCOBOL</strong> <strong>SAF</strong> director. Thus, it is<br />

necessary to modify the LINKAGE SECTION and PROCEDURE DIVISION when<br />

changing a CGI application into a <strong>SAF</strong> application. In addition, it is necessary to set<br />

the address of the interface area into COBW3, which is the interface with <strong>SAF</strong><br />

subroutines. For example:<br />

Contents of the CGI application<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

PROCEDURE DIVISION.<br />

MOVE LOW-VALUE TO COBW3.


120 Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong><br />

Modified contents of the <strong>SAF</strong> application<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

* COPY COBW3<strong>SAF</strong>.<br />

LINKAGE SECTION.<br />

01 <strong>SAF</strong>CTX POINTER.<br />

PROCEDURE DIVISION USING <strong>SAF</strong>CTX.<br />

MOVE LOW-VALUE TO COBW3.<br />

* MOVE LOW-VALUE TO COBW3<strong>SAF</strong><br />

SET COBW3-CONTEXT TO <strong>SAF</strong>CTX.<br />

* SET COBW3-<strong>SAF</strong>-CONTEXT TO <strong>SAF</strong>CTX.<br />

Note: Delete the comment indicators when using a <strong>SAF</strong> specific function.<br />

Environment Variable Operations<br />

An environment variable block is assigned to each process. Since CGI applications<br />

run as separate processes, each is responsible <strong>for</strong> its own environment variables and<br />

it will not interfere with other processes. However, an <strong>SAF</strong> application runs as<br />

several threads in NES process. Thus, the <strong>SAF</strong> application may affect NES or other<br />

applications if it modifies environment variables. Thus, it is necessary to make<br />

alterations in order to remove the use of environment variables when converting an<br />

application from CGI to <strong>SAF</strong>.<br />

It is not safe to assume that the current folder is unchanged when a <strong>SAF</strong> application<br />

is called. Thus, the user must pay attention to functions that use the current folder<br />

in the background, <strong>for</strong> example, a file operation specifying a relative path from the<br />

current folder. To avoid trouble, the following methods are recommended:<br />

• Specifying a file in an absolute path<br />

Contents of the CGI application<br />

MOVE "RESPONSE.HTM" TO COBW3-HTML-FILENAME.<br />

CALL "COBW3_PUT_HTML" USING COBW3.<br />

Modified contents of the <strong>SAF</strong> application<br />

MOVE "C:\COBOL\<strong>SAF</strong>\RESPONSE.HTM" TO COBW3-HTML-FILENAME.<br />

CALL "COBW3_PUT_HTML" USING COBW3.<br />

• Specifying a file position using the physical path corresponding to the virtual path<br />

Use COBW3_GET_REQUEST_INFO to acquire the physical path corresponding to<br />

the virtual path.<br />

Contents of the CGI application<br />

MOVE "RESPONSE.HTM" TO COBW3-HTML-FILENAME.<br />

CALL "COBW3_PUT_HTML" USING COBW3.


Modified contents of a <strong>SAF</strong> application<br />

Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong> 121<br />

SET COBW3-PHYSICALPATH TO TRUE<br />

CALL "COBW3_GET_REQUEST_INFO" USING COBW3.<br />

MOVE COBW3-REQUEST-INFO TO COBW3-HTML-FILENAME.<br />

MOVE "\RESPONSE.HTM" TO<br />

COBW3-HTML-FILENAME(COBW3-REQUEST-INFO-LENGTH + 1:13).<br />

CALL "COBW3_PUT_HTML" USING COBW3.<br />

• Using a value specified by the <strong>SAF</strong> director<br />

It is possible to acquire a set of a name and value specified with<br />

COBOL_Per<strong>for</strong>m in the obj.conf file, using COBW3_<strong>SAF</strong>_GET_PARM etc.<br />

Then, append path which Web application uses and the file name of the<br />

required file.<br />

Contents of the CGI application<br />

MOVE "RESPONSE.HTM" TO COBW3-HTML-FILENAME.<br />

CALL "COBW3_PUT_HTML" USING COBW3.<br />

Modified contents of the <strong>SAF</strong> application<br />

MOVE "APPPATH" TO COBW3-<strong>SAF</strong>-PARM-NAME.<br />

CALL "COBW3_<strong>SAF</strong>_GET_PARAM" USING COBW3<br />

IF COBW3-<strong>SAF</strong>-PARM-FLAG-EXIST THEN<br />

MOVE COBW3-<strong>SAF</strong>-PARM-VALUE TO COBW3-HTML-FILENAME<br />

MOVE "\RESPONSE.HTM" TO<br />

COBW3-HTML-FILNAME(COBW3-<strong>SAF</strong>-PARM-VALUE-LENGTH + 1:13)<br />

ELSE<br />

MOVE "Default-path-name\RESPONSE.HTM" TO COBW3-HTML-FILENAME<br />

END-IF.<br />

CALLL "COBW3_PUT_HTML" USING COBW3.<br />

Setting of the <strong>SAF</strong> director in the obj.conf file<br />

Service method=(GET|POST) type="magnus-internal/cob-app"<br />

sev="0" APPPATH="C:/COBAPL/APP"<br />

File specification in the run-time initialization file (COBOL85.CBR) is related to this.<br />

<strong>SAF</strong> applications cannot use relative paths, whereas either an absolute path or a<br />

relative path may be set <strong>for</strong> a CGI application. No substitute method is available, so<br />

the run-time initialization file must be modified to allow absolute paths to be set.<br />

COBOL85.CBR of the CGI application<br />

[Program name]<br />

Access-name=SEQFILE.DAT<br />

COBOL85.CBR modified <strong>for</strong> the <strong>SAF</strong> application<br />

[Program name]<br />

Access-name=C:\COBOL\<strong>SAF</strong>\SEQFILE.DAT


122 Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong><br />

Operations of CGI Environment Variables<br />

A CGI application can reference the "CGI environment variables" using the<br />

environment variable operation function of COBOL. On the contrary, an <strong>SAF</strong><br />

application cannot reference them. Thus, it uses three subroutines shown below:<br />

• COBW3_RECEIVE _HEADER<br />

This subroutine acquires an HTTP header.<br />

• COBW3_GET_REQUEST_INFO<br />

This subroutine acquires various types of in<strong>for</strong>mation related to a request.<br />

• COBW3_GET_AUTHORIZE<br />

This subroutine acquires authorization in<strong>for</strong>mation.<br />

In addition, a CGI application can set or reference Cookie data using the<br />

environment variable operation function of COBOL. An <strong>SAF</strong> application cannot<br />

handle Cookie data using the environment variable operation function of COBOL.<br />

Use the subroutines <strong>for</strong> handling Cookie data shown below.<br />

• COBW3_SET_COOKIE, etc.<br />

This subroutine registers Cookie data.<br />

• COBW3_DEL_COOKIE, etc.<br />

This subroutine deletes registered Cookie data.<br />

• COBW3_INIT_COOKIE<br />

This subroutine initializes Cookie data to be sent to the client.<br />

• COBW3_GET_COOKIE, etc.<br />

This subroutine acquires Cookie data contained in a request.<br />

For example, modify processing <strong>for</strong> acquiring in<strong>for</strong>mation from the HTTP header as<br />

shown below.<br />

Contents of the CGI application<br />

DISPLAY "HTTP_USER_AGENT” UPON Environment-variable-name.<br />

ACCEPT Browser-in<strong>for</strong>mation FROM Value-of-the-environment-variable<br />

ON EXCEPTION<br />

MOVE "Error" TO Browser-in<strong>for</strong>mation<br />

END-ACCEPT.<br />

Modified contents of the <strong>SAF</strong> application<br />

MOVE "User-agent" TO COBW3-HEADER-NAME.<br />

CALL "COBW3_RECEIVE_HEADER" USING COBW3.<br />

IF COBW3-STATUS = ZERO THEN<br />

MOVE COBW3-HEADER-VALUE TO Browser-in<strong>for</strong>mation<br />

ELSE<br />

MOVE "Error" TO Browser-in<strong>for</strong>mation<br />

END-IF.


Modify Cookie operation as shown below.<br />

Contents of the CGI application<br />

Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong> 123<br />

DATA DIVISION.<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

01 COOKIEDATA.<br />

02 PIC X(19) VALUE "Sample+cookie+data=".<br />

02 COOKIEVALUE PIC X(32).<br />

PROCEDURE DIVISION.<br />

:<br />

DISPLAY "HTTP_COOKIE" UPON Environment-variable-name.<br />

ACCEPT COOKIEVALUE FROM Value-of-the-environment-variable<br />

ON EXCEPTION<br />

MOVE "Error" TO COOKIEVALUE<br />

END-ACCEPT.<br />

Modified contents of the <strong>SAF</strong> application<br />

DATA DIVISION.<br />

WORKING-STORAGE SECTION.<br />

COPY COBW3.<br />

01 COOKIEVALUE PIC X(32).<br />

:<br />

PROCEDURE DIVISION USING <strong>SAF</strong>CTX.<br />

:<br />

MOVE "Sample cookie data" TO COBW3-COOKIE-NAME.<br />

CALL "COBW3_GET_COOKIE" USING COBW3.<br />

IF COBW3-STATUS = ZERO THEN<br />

MOVE COBW3-COOKIE-VALUE TO COOKIEVALUE<br />

ELSE<br />

MOVE "Error" TO COOKIEVALUE<br />

END-IF.<br />

Note: The user must execute URL encoding and URL decoding of Cookie data when<br />

handling the Cookie data by means of environment variable operation. To avoid<br />

such encoding and decoding, use Cookie data consisting of alphanumeric characters<br />

only.<br />

For example, an en-size space becomes a "+" as a result of URL encoding.


124 Appendix D. CGI To <strong>SAF</strong> <strong>Subroutines</strong> Conversion <strong>Guide</strong>

Hooray! Your file is uploaded and ready to be published.

Saved successfully!

Ooh no, something went wrong!