NetCOBOL for SPARC Architecture SAF Subroutines User's Guide

SAF Subroutines 

User’s Guide

Ninth Edition: August 2008 

The contents of this manual may be revised without prior notice. No part of this document may 

be reproduced or transmitted in any form or by any means, electronic or mechanical, for any 

purpose, without the express written permission of Fujitsu Limited. 

© 1996-2008 Fujitsu Limited. All Rights Reserved.

Preface 

This manual explains how to generate a COBOL program using NetCOBOL SAF 

Subroutines 3.1, as well as how to execute the program and debug it. 

See also "NetCOBOL User's Guide" for creation, compilation, and execution of COBOL 

programs. 

For debugging of COBOL programs, see “NetCOBOL Debugging Guide”. 

See "NetCOBOL Language Reference" for syntax rules of COBOL. 

To generate a Web application that runs in Unicode, see also Appendix B in the 

"NetCOBOL Web Guide." 

Supported Environments 

NetCOBOL SAF Subroutines 3.1 run in 32-bit mode in the following systems and 

provides 32-bit development and operating environments for applications running 

with Netscape Enterprise Server 3.6 with SP3 or later or iPlanet Web Server 

Enterprise Edition 4.0 or later. 

• 

Microsoft® Windows® 2000 Server operating system 

• Microsoft® Windows® 2000 Advanced Server operating system 

Trademarks 

Trademarks mentioned in this manual are as follows: 

NetCOBOL is a trademark or registered trademark of Fujitsu Limited or its 

subsidiaries in the United States or other countries or in both. 

Microsoft and Windows are registered trademarks of Microsoft Corporation in the 

United States and other countries. 

Netscape, Netscape Navigator, and Netscape Enterprise Server are 

trademarks/registered trademarks of Netscape Communications Corporation in the 

United States and other countries. 

Other company names and product names are trademarks/registered trademarks of 

each company concerned. 

Permission for using screenshots was obtained from Microsoft Corporation, U.S. 

NetCOBOL SAF Subroutines User's Guide 3

Product Names 

Names of products described in this manual are abbreviated as: 

Product Name Abbreviation 

Microsoft® Windows® 2000 Server operating system Windows® 2000 

Microsoft® Windows® 2000 Advanced Server operating 

system 

Windows® 2000 

Microsoft® Internet Explorer IE 

Netscape Enterprise Server 3.6 with SP3 NES 

4 NetCOBOL SAF Subroutines User's Guide

Contents 

Chapter 1. NetCOBOL SAF Subroutines .......................................................7 

Overview of SAF................................................................................................. 7 

NetCOBOL SAF Subroutines................................................................................. 7 

Chapter 2. Creating Web Applications Using SAF Subroutines....................9 

Requirements....................................................................................................10 

What to Generate..............................................................................................10 

Using Assist Functions for Web Application Development ......................................13 

Chapter 3. How to Use SAF Subroutines....................................................15 

SAF Subroutine Functions...................................................................................15 

SAF Subroutines Interface..................................................................................23 

Set the Work Environment and Acquire Web Parameter........................................24 

Manipulate Web Parameters...............................................................................25 

Output Processing Results..................................................................................28 

Execute System Commands................................................................................45 

Free SAF Execution Environment Resources.........................................................45 

Get Request Information....................................................................................46 

Manipulate Cookie Data .....................................................................................49 

Manipulate Uploaded Files..................................................................................55 

Manage Sessions...............................................................................................60 

SAF-Specific Subroutines....................................................................................64 

Data Length Restrictions of SAF Subroutines........................................................67 

Classes Provided by SAF Subroutines ..................................................................67 

Chapter 4. Generating and Executing a Web Application...........................69 

Executing a Web Application ..............................................................................70 

Compiling and Linking........................................................................................70 

NES Settings .....................................................................................................71 

Defining the Web Application to the SAF Director .................................................71 

Executing a Web Application ..............................................................................77 

SAF Director Reference ......................................................................................77 

NetCOBOL SAF Subroutines User’s Guide 5

Chapter 5. Debugging a SAF Application ...................................................81 

Referring to the Log Information ........................................................................82 

Checking Execution Using the Interactive Debugger .............................................82 

Displaying Errors Detected by SAF Subroutines ....................................................84 

Displaying Working-Storage Data or Messages in a Web Page...............................85 

Chapter 6. Samples ....................................................................................87 

Program Files Provided ......................................................................................88 

Subroutines Used ..............................................................................................88 

Program Compiling ............................................................................................88 

Program Linkage ...............................................................................................88 

Environment Setup ............................................................................................89 

Sample Execution..............................................................................................89 

Explanation of Samples......................................................................................89 

Appendix A. Frequently Asked Questions ..................................................97 

Appendix B. Error Recovery Processing...................................................105 

Appendix C. Architecture of a NetCOBOL SAF Application ......................113 

Appendix D. CGI To SAF Subroutines Conversion Guide .........................115 

Conversion from CGI to SAF .............................................................................116 

Application Form .............................................................................................117 

Web Pages for Invoking Applications.................................................................117 

Compilation and Linking Methods......................................................................118 

Unit of Execution.............................................................................................118 

Compilation Method.........................................................................................119 

Accessing Common Resources..........................................................................119 

Server Interface Area.......................................................................................119 

Environment Variable Operations ......................................................................120 

Operations of CGI Environment Variables ..........................................................122 

6 NetCOBOL SAF Subroutines User's Guide

Chapter 1. NetCOBOL SAF Subroutines 

Overview of SAF 

SAF (Server Application Functions) is an application generated by using the NSAPI 

(Netscape Server Application Programming Interface). 

The NSAPI is an interface provided for extending the NES (Netscape Enterprise 

Server). SAF is included in the NES and runs as a thread so that it operates faster 

than CGI. It can save resource consumption including memory. Since SAF operates 

as a thread, however, the thread must be thread safe. If resources have not been 

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

must be taken. 

Browser 

Browser 

Request 

Response 

Request 

Response 

NetCOBOL SAF Subroutines 

Process 

Thread 

SAF 

Thread 


NSAPI 

The Web subroutines using NSAPI are called NetCOBOL SAF subroutines (hereafter, 

called SAF subroutines). The environment in which Web applications are generated 

by using SAF subroutines is called the NetCOBOL SAF director (hereafter, called SAF 

director). The SAF director loads and executes Web applications generated by using 

the SAF subroutines. The Web applications are loaded when NES is started or at 

initial request, and the application resides in memory after that. The applications are 

not unloaded until NES is terminated.

8 Chapter 1. NetCOBOL SAF Subroutines 

Browser 

NES 

Loads into 

the start 

time 


Director 

Loads into the 

start or access 

time 

COBOL 

Application 

The SAF director and the Web applications to be executed run as SAFs so that 

features of SAF are inherited by the Web applications. Since the SAF subroutines 

have higher-order compatibility than the CGI subroutines, Web applications that use 

CGI subroutines can be easily converted to Web applications under NES with some 

minor modifications.

Chapter 2. Creating Web Applications Using 

SAF Subroutines 

This chapter describes how to use SAF subroutines to create web applications. It 

includes these topics: 

• System requirements 

• Resource requirements 

• How to use assist functions in the COBOL Project Manager

10 Chapter 2. Creating Web Applications Using SAF Subroutines 

Requirements 

The following are required for creating SAF subroutine applications. 

• Netscape Enterprise Server 3.6with SP3 or later or iPlanet Web Server Enterprise 

Edition 4.0 or later required for executing the Web applications 

• Fujitsu COBOL V61L10 or later or NetCOBOL V7.0L10 or later required for 

compiling, linking, and executing the Web applications 

When operating it, the NetCOBOL server operation package is necessary. 

Note: Ask the system administrator of your WWW server regarding the 

requirements of installing and setting up . 

What to Generate 

To generate SAF applications by using SAF subroutines, the following must be 

generated . 

• COBOL program to which any entry-name is assigned by using the SAF 

subroutines and a resulting .DLL generated with the entry-name as an export 

function 

See Chapter 4 "Compiling and linking" for explanations of compiling and linking 

these programs. 

• 

HTML document 

- Web page for invoking each application (for starting the Web application) 

- Web page for processing result output (for returning processing results, to 

be generated on demand) 

Explanations of these items are given in the following sections. 

COBOL Programs using SAF Subroutines 

It is possible to specify any name that can be specified in COBOL to the entry name 

of the COBOL program. To make this COBOL program operate as SAF, the SAF 

subroutine must be used. 

Given below are requirements for generating COBOL programs that execute as SAF 

applications. 

IDENTIFICATION DIVISION: 

None 

ENVIRONMENT DIVISION: 

None 

DATA DIVISION: 

• WORKING-STORAGE SECTION 

Include the SAF interface data area description by using a COPY statement.

WORKING-STORAGE SECTION. 

COPY COBW3 

Chapter 2. Creating Web Applications Using SAF Subroutines 11 

To use SAF specific functions, include the SAF specific data area. 


COPY COBW3. 

COPY COBW3SAF. *>Interface with a SAF specific subroutine 

These libraries (COBW3.cbl and COBW3SAF.cbl) are stored in the folder in which 

Fujitsu NetCOBOL has been installed. 

• LINKAGE SECTION 

Define a pointer item for the interface with NES. 

LINKAGE SECTION. 

01 SAFCTX POINTER. 

PROCEDURE DIVISION 

Write the following in order to conform to the calling conventions of NES. 

PROCEDURE DIVISION USING SAFCTX. 

SAFCTX obtained above is required for the SAF subroutines to communicate with 

NES, so initialize COBW3-CONTEXT as follows. 

MOVE LOW-VALUE TO COBW3. 

SET COBW3-CONTEXT TO SAFCTX. 

To use SAF specific functions, initialize COBW3-SAF-CONTEXT. 

MOVE LOW-VALUE TO COBW3SAF. 

SET COBW3-SAF-CONTEXT TO SAFCTX. 

Given the sample settings above, the skeleton of this program would appear as 

follows: 

IDENTIFICATION DIVISION. 

PROGRAM-ID. "SAFAPL". 

ENVIRONMENT DIVISION. 

DATA DIVISION. 


COPY COBW3. 

* COPY COBW3SAF. 




* 


* MOVE LOW-VALUE TO COBW3SAF. 


* SET COBW3-SAF-CONTEXT TO SAFCTX 

* 

* Write the process on demand. 

* 

EXIT PROGRAM.

12 Chapter 2. Creating Web Applications Using SAF Subroutines 

Web Page for Invoking Application 

Prepare a normal HTML document. To start the Web application, however, use the 

tag or tag. 

Example: 

When executing the generated dynamic link library SAF.dll in METHOD = "POST" 

 

Note: When the Web application is started by using an tag, the Web 

parameter list cannot be obtained by the program. 

Make a setting on NES so that the extension “apl1” would correspond to SAF .dll 

containing the application. For details, see "NES setup" in Chapter 4 . 

For explanations concerning other HTML documents, see Appendix A of "NetCOBOL 

Web Guide." 

Web Page for Processing Result Output 

The Web page for processing result output is an HTML document for returning the 

result of the Web application to the WWW browser. It is not necessary to create a 

Web page for processing result output because the response data, including the 

requisite HTML, can be returned directly from the Web application. If the Web page 

for processing result output is separate from the application program, however, then 

it is possible to change the layout of the output results without recompiling the Web 

application. 

To output the static HTML document (HTML document whose output data does not 

change due to process results), it is possible to use the HTML document generated 

with the HTML generation tool. 

It is also possible to dynamically change the format of the Web page for processing 

result output . 

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

output Web page enables dynamic data conversion . Since all data in an HTML 

document can be a target for replacement, it is also possible to replace a tag for 

changing text or specifying the background color. For details, see 

"COBW3_PUT_HTML" in Chapter 3 "Processing result output." 

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

for output and to output the divided document in combination with plain text. 

Notes: 

• Do not use the following functions related to screen operation in the COBOL 

program to be used in the Web application. For details, see Chapter 21 

"Programs Running under a Service" in "NetCOBOL User's Guide." 

- Presentation file module (Screen handling module) 

- Screen handling module 

- ACCEPT/DISPLAY function 

(Modules handling environment variables, dates, and time, however, can be 

used.)

• 

• 

• 

• 

• 

Chapter 2. Creating Web Applications Using SAF Subroutines 13 

Before using SAF subroutines, the pointer item to be passed with the parameter 

must be set to COBW3-CONTEXT. 

The pointer item passed with COBW3, COBW3SAF, and the parameter must not 

be shared among multiple threads. NES may not operate normally. 

Do not specify REPLACING in the COPY statement that includes libraries 

(COBW3.cbl, COBW3SAF.cbl) provided by SAF subroutines. Do not write any 

REPLACE statement that may make the COPY statement a target for replacing. 

Do not modify the value of the pointer item passed with the parameter. If 

changed, the operation is not guaranteed. 

When the data is initialized (VALUE clause) in the DATA DIVISION, the initial 

value assigned for multiple requests is not guaranteed in some operating 

environments. If it is necessary to guarantee the initial value in every request 

from the WWW browser, the data must be initialized in the PROCEDURE 

DIVISION . 

Using Assist Functions for Web Application Development 

The COBOL Project Manager provides assist functions for Web application 

development. 

A COBOL program using SAF subroutines can be easily generated by using the Web 

application wizard of the COBOL Project Manager. Since the Web application 

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

the generated program. 

For details of assist functions for Web application development, see "Web 

Development Tools Guide."

14 Chapter 2. Creating Web Applications Using SAF Subroutines

Chapter 3. How to Use SAF Subroutines 

This chapter lists and describes each of the NetCOBOL SAF subroutines. 

SAF Subroutine Functions 

The SAF subroutines provide functions as follows: 

Basic Functions 

These are the basic functions used in creating a NetCOBOL SAF Web application. 

Function Subroutine name Usage 

Setting the work 

environment and getting 

the Web parameter 

Web parameter operation 

Processing result output 

COBW3_INIT Setting the work environment for SAF 

subroutines and getting the Web parameter 

COBW3_GET_VALUE Searching NAME in the Web parameter and 

COBW3_GET_VALUE_XX 

getting VALUE 

COBW3_GET_VALUE_NX 

COBW3_GET_VALUE_XN 

COBW3_GET_VALUE_NN 

COBW3_CHECK_VALUE Searching VALUE in the Web parameter 

COBW3_CHECK_VALUE_X 

COBW3_CHECK_VALUE_N 

COBW3_PUT_HEAD Header output 

COBW3_PUT_HTML Outputting the Web page for processing 

result output 

COBW3_SET_CNV 

Setting the converted data in the Web page 

COBW3_SET_CNV_XX 

for processing result output 

COBW3_SET_CNV_NX 

COBW3_SET_CNV_XN 

COBW3_SET_CNV_NN 

COBW3_DEL_CNV 

Deleting the converted data in the Web page 

COBW3_DEL_CNV_X 

for processing result output 

COBW3_DEL_CNV_N 

COBW3_INIT_CNV Initializing the converted data in the Web 

page for processing result output 

COBW3_SET_REPEAT Setting the repeated conversion data in the 

COBW3_SET_REPEAT_XX 

Web page for processing result output 

COBW3_SET_REPEAT_NX 

COBW3_SET_REPEAT_XN 

COBW3_SET_REPEAT_NN

16 Chapter 3. How to Use SAF Subroutines 

Processing result output 

System command 

execution 

Releasing resources of 

SAF execution 

environment 

Getting request 

information 

Cookie data operation 

COBW3_DEL_REPEAT Deleting the repeated conversion data in the 

COBW3_DEL_REPEAT_X 

COBW3_DEL_REPEAT_N 

Web page for processing result output 

COBW3_INIT_REPEAT Initializing the repeated conversion data in 

the Web page for processing result output 

COBW3_PUT_TEXT Data output (line feed code added) 

COBW3_SYSTEM Executing the system command specified 

COBW3_FREE Releasing resources obtained by the SAF 

subroutine 

COBW3_RECEIVE_HEADER Getting the HTTP header 

COBW3_GET_REQUEST_INF Getting information related to requests 

O 

COBW3_GET_AUTHORIZE Getting authorization information 

COBW3_SET_COOKIE Setting Cookie data 

COBW3_SET_COOKIE_XX 

COBW3_SET_COOKIE_NX 

COBW3_SET_COOKIE_XN 

COBW3_SET_COOKIE_NN 

COBW3_DEL_COOKIE Deleting Cookie data that has been set 

COBW3_DEL_COOKIE_X 

COBW3_DEL_COOKIE_N 

COBW3_INIT_COOKIE Initializing all Cookie data that has been set 

COBW3_GET_COOKIE Getting Cookie data with the Web parameter 

COBW3_GET_COOKIE_XX 

COBW3_GET_COOKIE_NX 

COBW3_GET_COOKIE_XN 

COBW3_GET_COOKIE_NN 

• It is necessary to use the following subroutines in an ASCII environment. 

COBW3_GET_VALUE 

COBW3_CHECK_VALUE 

COBW3_SET_CNV 

COBW3_DEL_CNV 

COBW3_SET_REPEAT 

COBW3_DEL_REPEAT 

COBW3_SET_COOKIE 

COBW3_DEL_COOKIE 

COBW3_GET_COOKIE

• In the Unicode environment, use the following subroutines: 

• 

Subroutine name Explanation 

Chapter 3. How to Use SAF Subroutines 17 

COBW3_xxxxx_XX Both NAME and VALUE parameters are regarded as alphanumeric 

data items. 

COBW3_xxxxx_NX NAME parameter is regarded as a national data item and VALUE 

parameter is regarded as an alphanumeric data item. 

COBW3_xxxxx_XN NAME parameter is regarded as an alphanumeric data item and 

VALUE parameter is regarded as a national data item. 

COBW3_xxxxx_NN Both NAME and VALUE parameters are regarded as national data 

items. 

COBW3_xxxxx_X The Input parameter is regarded as an alphanumeric data item. 

COBW3_xxxxx_N The Input parameter is regarded as a national data item. 

Any code system can use the SAF subroutines not listed above. 

File Upload Function 

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

This function is valid in the following cases: 

• When a large amount of data which may cause timer expiration in online 

processing is to be entered. 

• When a mobile environment with meter-rate accounting is to be used. 

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

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

data entry tool into a Web tool. 

• When only the HTTP ports can be accessed in file transfer because of security 

conditions. (File transfer in conventional systems is done using FTP.) 

Using the file upload function, file transfer can be associated with applications. 

Therefore, data can be checked and registered immediately after file transfer.


Client 

File upload processing is shown below: 

File-A 

C:\ File-A Browse 

Registration 

completion!! 

Send 

Server 

Set of name of file to be transferred 

WWW 

Server 

: Processing flow 

Web Application 

Acquisition of upload 

file information 

Generation of file 

Extraction of data 

from file 

Registration of extracted 

data into DB 

Deletion of file 

: 

Uploaded File-A 

Database 

Function provided by Web 

subroutines

Web page for invoking the applications 

: 

 

 

Send file: 

 

 

 

: 


Web application (COBOL source) 

: 


COPY COBW3. 

PROCEDURE DIVISION. 

* 

CALL “COBW3_INIT” USING COBW3. 

* 

*GET INFORMATION OF UPLOADED FILE 

MOVE “UPFILE” TO 

COBW3-SEARCH-DATA. 

CALL “COBW3_GET_UPLOADFILE_INFO” 

USING COBW3. 

IF COBW3-SEARCH-FLAG-NON THEN 

Error Processing 

END-IF. 

*SET GENERATION FILE-NAME 

MOVE “File-A” TO 

COBW3-UPLOADED-FILENAME. 

CALL “COBW3_GEN_UPLOADFILE” 

USING COBW3. 

IF COBW3-STATUS NOT = ZERO THEN 

Error Processing 

END-IF. 

************************************************* 

* 

* Any processing for uploaded files 

* 

************************************************* 

*DELETION UPLOADED FILES 

CALL “COBW3_DEL_UPLOADFILE” 

USING COBW3. 

CALL “COBW3_PUT_HTML” 

USING COBW3. 

CALL “COBW3_FREE” USING COBW3.


Web subroutines provide the following functions to easily create such application 

programs: 


File upload COBW3_GET_UPLOADFILE_INFO Acquires the information on an 

COBW3_GET_UPLOADFILE_INFO_X 

COBW3_GET_UPLOADFILE_INFO_N 

upload file. 

COBW3_GEN_UPLOADFILE 

Generates an uploaded file on the 

COBW3_GEN_UPLOADFILE_X 

COBW3_GEN_UPLOADFILE_N 

server. 

COBW3_DEL_UPLOADEDFILE Deletes an uploaded file. 

To upload a file, the following values must be written on the Web page for invoking 

an application: 

Tag name Attributes Value 

FORM 

METHOD POST 

ENCTYPE multipart/form-data 

INPUT TYPE file 

For details of these tags and attributes, see the “NetCOBOL Web Guide” and other 

documents or home pages that explain HTML. 

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

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

can be acquired by a subroutine such as COBW3_GET_VALUE regardless of whether 

the file upload function is used. 

Note: The NAME value specified in the INPUT tag (TYPE=”file”) for uploading files 

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

Otherwise, the normal operation of the Web subroutine is not assured. 

For example: 

: 

 

Do not specify 

:

Session Management Functions 


Using the session management functions enables Web applications to handle 

multiple requests from a specific client session (WWW browser). 


Session 

COBW3_START_SESSION Starting the session 

management 

COBW3_END_SESSION Terminating the session 

COBW3_SET_SESSION_DATA Setting the session data 

COBW3_GET_SESSION_DATA Getting the session data 

COBW3_ALTER_SESSION_TIME 

OUT 

Changing the time of session timeout 

COBW3_GET_SESSION_INFO Getting the current session 


The session management functions cannot be used with COBOL CGI subroutines. 

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

by using the session management functions for opening the session. In a single 

session, the data entered on a previous page can be inherited by a subsequent page 

using the session data functions. 

WWW Browser WWW Server 

Screen1 

Screen2 

Screen3 

Web 

Application 1 

Web 

Application 2 

Session data 

is inherited 

Session 

start 

Session 

end 

A session time-out occurs when the client session transmits no data for an extended 

period or when the transaction is interrupted due to some reason such as the WWW 

browser being closed before completing the session . 

A time-out occurs when the time counted from when the Web application returned a 

response to the WWW browser to when the next request is issued by the WWW 

browser in the same session has exceeded the specified time. When a time-out 

occurs, the session management terminates the session leaving the application’s 

resources in the same status as when the session was interrupted . To cope with 

such a status, the session management functions provide a registration mechanism 

of time-out processing.


WWW Browser WWW Server 

Screen1 

Screen2 

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

button for which SUBMIT is specified as the TYPE attribute of the INPUT tag, the 

applications will not operate properly. The programmer should prevent the 

inadvertent starting of multiple applications by using JavaScript in the WWW 

browser. See "NetCOBOL Web Guide" for general notes on WWW browser 

operation. 

SAF-Specific Functions 

After a long time 

passes, access to the 

Web application 

Web 

Application 1 

TIMEOUT 

Web 

Application 2 

SAF specific functions enable getting information specifically related to NES . 

Listed below are SAF specific subroutines. 


Getting NES setting COBW3_SAF_GET_PARM Getting the parameter specified to 

COBW3_SAF_GET_PARM_XX 

COBW3_SAF_GET_PARM_NX 

COBW3_SAF_GET_PARM_XN 

COBW3_SAF_GET_PARM_NN 

the SAF director 

Getting request COBW3_SAF_GET_BASENAME Getting the application name 


specified to the URL 

Note: Use the following subroutine in an ASCII environment: 

COBW3_SAF_GET_PARAM 

Session 

start 

Timeout 

processing 

Session data 

is forced 

Session data 

cannot be 

inherited

SAF Subroutines Interface 


This section explains the calling interface for using the SAF subroutines. 

Note: It is possible to check errors and warning in the SAF subroutines by referring 

to COBW3-STATUS, and those in SAF specific subroutines by referring to COBW3- 

SAF-STATUS. 

Value Meaning 

0 Normal end 

Not zero Error number 

See Appendix B "Error Recovery Processing" for error numbers. 

Library 

The library file is a COPY member for use as a SAF data area. When calling SAF 

subroutines, include the following library file in the Working-Storage Section with a 

COPY statement. This library file is stored in the folder in which Fujitsu NetCOBOL 

has been installed. 

Library name: COBW3.cbl 

Format: Specify as follows: 


COPY COBW3. 

To call SAF specific subroutines, include the SAF specific data area using the COPY 

statement. This library is also stored in the folder to which Fujitsu NetCOBOL has 

been installed. 

Library name: COBW3SAF.cbl 

Format: Specify as follows: 


COPY COBW3. 

COPY COBW3SAF. *> Interface with a SAF specific subroutine 

Note: Do not specify REPLACING in the COPY statement of a SAF data area or write 

a REPLACE statement that might make the COPY statement a target for replacing. 

If names in the SAF data area are changed, the operation is not guaranteed. 

Calling SAF Subroutines 

In order to initialize the environment of the SAF subroutines and to get the Web 

page parameter list, it is necessary to call COBW3_INIT before calling any other SAF 

function. When terminating the processing for SAF subroutines, COBW3_FREE must 

be called to release resources acquired by the SAF subroutines. 

When calling other subroutines from a program that is not the one which called 

COBW3_INIT, the interface area (COBW3) defined in the program which called 

COBW3_INIT is shared among programs.


Example: Calling COBW3_INIT by the parent program and calling COBW3_FREE by 

the child program B. 

Parent program 


PROGRAM-ID. "MainProc". 



COPY COBW3. 





MOVE SAFCTX TO COBW3-CONTEXT. 

CALL "COBW3_INIT" USING COBW3. 

: 

CALL "B" USING COBW3 

* 

EXIT PROGRAM. 

Child program 


PROGRAM-ID. B. 



COPY COBW3 

PROCEDURE DIVISION USING COBW3. 

: 

CALL "COBW3_FREE" USING COBW3. 

EXIT PROGRAM. 

Set the Work Environment and Acquire Web Parameter 

COBW3_INIT 

Set the work environment for SAF subroutines. Get a Web parameter and set it to 

the work area to be used by SAF subroutines. 

Note: Initialize COBW3 in the interface area with LOW-VALUE before calling 

COBW3_INIT. 

Format: 


COBW3 Data for Call: 

• 

• 

COBW3-CONTEXT [required] 

Specify the Linkage Section pointer to the data work area with the SAF director. 

Do not change the specified value. 

COBW3-DMODE [optional] 

Specify error message output of SAF subroutines. 

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

Condition-name Value Meaning 


COBW3-DMODE-NODBG LOW-VALUE No error message is output. 

COBW3-DMODE-DBG "1" An error message is output to the browser. 

Processing Result Data: 

None. 

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

obtained may be reinitialized and subsequent operations may fail. 

Manipulate Web Parameters 

COBW3_GET_VALUE, COBW3_GET_VALUE_XX, 

COBW3_GET_VALUE_NX, COBW3_GET_VALUE_XN, 


Search a field name (NAME) from the Web parameter obtained in COBW3_INIT and 

return the value (VALUE) corresponding to the name. 

ASCII environment: 

• COBW3_GET_VALUE 

Search the name (NAME) of an alphanumeric character-string and return the 

value (VALUE) corresponding to the name as an alphanumeric character-string. 

Unicode environment: 

• COBW3_GET_VALUE_XX 

Search the name (NAME) of an alphanumeric character-string and return the 

value (VALUE) corresponding to the name as an alphanumeric character-string. 

• COBW3_GET_VALUE_NX 

Search the name (NAME) of a national character-string and return the value 

(VALUE) corresponding to the name as an alphanumeric character-string. 

• COBW3_GET_VALUE_XN 

Search the name (NAME) of a alphanumeric character-string and return the 

value (VALUE) corresponding to the name as a national character-string. 

• COBW3_GET_VALUE_NN 

Search the name (NAME) of a national character-string and return the value 

(VALUE) corresponding to the name as a national character-string. 

Padding characters for storing the obtained value (VALUE) are blank. 

Format: 

CALL "COBW3_GET_VALUE" USING COBW3.


• 

• 

CALL "COBW3_GET_VALUE_XX" USING COBW3. 

CALL "COBW3_GET_VALUE_NX" USING COBW3. 

CALL "COBW3_GET_VALUE_XN" USING COBW3. 

CALL "COBW3_GET_VALUE_NN" USING COBW3. 

COBW3 Data for Calls:COBW3-SEARCH-DATA, COBW3-SEARCH-DATA-N 

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

name in the HTML document that invokes the application.) 

Set to COBW3-SEARCH-DATA for COBW3_GET_VALUE, COBW3_GET_VALUE_XX 

and COBW3_GET_VALUE_XN. 

Set to COBW3-SEARCH-DATA-N for COBW3_GET_VALUE_NX or 

COBW3_GET_VALUE_NN. 

COBW3-SEARCH-LENGTH [Optional] 

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

character-string length (byte length) of the name containing the space. 

Value Meaning 

0 Search up to the last character that is not a space. 

1 to 1024 Search up to the length of the character-string specified. 

• COBW3-NUMBER [Optional] 

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

occurrence number of the target name to be searched . 


COBW3-NUMBER-INIT 1 Search the first name that matches. 

- - - - - 2 to 9999 Search the specified occurrence of the name. 


• COBW3-SEARCH-FLAG 


COBW3-SEARCH-FLAG 

-NON 

"0" The target name for searching is not found. 


-EXIST 

"1" The target name for searching is found.

• 

• 


COBW3-GET-DATA, COBW3-GET-DATA-N 

The value (VALUE) corresponding to the name (NAME) is set. 

Set to COBW3-GET-DATA for COBW3_GET_VALUE, COBW3_GET_VALUE_XX and 

COBW3_GET_VALUE_NX. 

Set to COBW3-GET-DATA-N for COBW3_GET_VALUE_XN or 

COBW3_GET_VALUE_NN. 

COBW3-GET-LENGTH 

The character-string length (byte length) of the value (VALUE) corresponding to 

name (NAME) to be searched is set. 

COBW3_CHECK_VALUE, COBW3_CHECK_VALUE_X, 


Search for a value (VALUE) in the Web data area obtained in COBW3_INIT. This 

subroutine is used for determining the presence of a selected check box item in the 

data area from the Web page 


• COBW3_CHECK_VALUE 

Search the value (VALUE) of an alphanumeric character-string. 


• COBW3_CHECK_VALUE_X 

Search the value (VALUE) of an alphanumeric character-string. 

• COBW3_CHECK_VALUE_N 

Search the value (VALUE) of a national character-string. 

Format: 

CALL "COBW3_CHECK_VALUE" USING COBW3. 

CALL "COBW3_CHECK_VALUE_X" USING COBW3. 

CALL "COBW3_CHECK_VALUE_N" USING COBW3. 

COBW3 Data for Calls: 

• COBW3-SEARCH-DATA and COBW3-SEARCH-DATA-N 

Set a value to be searched for. 

Set the value in COBW3-SEARCH-DATA if it is COBW3_CHECK_VALUE or 

COBW3_CHECK_VALUE_X. 

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


• COBW3-SEARCH-LENGTH [Optional] 

Set the character length of a value with a valid space at the end to the number 

of bytes including the space. 

Value Meaning 

0 The length to the last character, excluding the space, is checked. 

1 to 1024 Values of the specified character length are searched for. 

• COBW3-NUMBER [Optional] 

Set the sequential order of a value to be searched for if there are several 

equivalent values in the web parameter. 


COBW3-NUMBER-INIT 1 The value found first is selected. 

- - - - - 2 to 9999 The value of the specified occurrence is 

searched for. 





-NON 

"0" No applicable values exist. 


-EXIST 

"1" Applicable values exist. 

Output Processing Results 

COBW3_PUT_HEAD 

This subroutine outputs a specified header. 

When an HTML document designed for processing result output (prototype file) is 

used, the header is output using the text/html SAF subroutine. Thus, it is 

unnecessary to use this subroutine to output the header. Use this subroutine only to 

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

header. 

Note: Use this subroutine before using COBW3_PUT_HTML or COBW3 PUT TEXT. 

If it is used after COBW3_PUT_HTML or COBW3_PUT_TEXT, the information 

becomes invalid as a header. 

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

or COBW3-STATUS-CODE. 

Format: 

CALL “COBW3_PUT_HEAD” USING COBW3.



• COBW3-PUT-HEAD 

Set a character string to be output to the header. 

• COBW3-PUT-HEAD-LENGTH [Optional] 

Set the length of a character string with a valid space at the end to the number 

of bytes including the space. 

Value Meaning 

0 Character strings of any length, excluding terminating at the first space, are 

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

character only) if COBW3-PUT-HEAD is filled with spaces only. 

1 to 512 Character strings of the specified character length are output. 

• COBW3- CONTENT-TYPE [Optional] 

Set a file type (Content-type) of response data. 

When this subroutine is called several times, the first file type is used. 


- - - - - LOW-VALUE An HTML document is output. 

COBW3-CONTENT-TYPE 

-NON 

HIGH-VALUE Content-type is not output. 


-HTML 

“text/htm1” An HTML document is output. 


-TEXT 

“text/plain” A text file is output. 

- - - - - - - - Any character Any character string is set in Content-type 

string 

of the header. 

• COBW3-STATUS-CODE [Optional] 

Set status code. 

When this subroutine is called several times, the first status code is validated. 


- - - - - - - - LOW-VALUE The normal end code "200" is output to 

Status-code. 

COBW3-STATUS-CODE 

-NON 

HIGH-VALUE Status-code is not output. 

COBW3-STATUS-CODE 

–200 

“200” The normal end code "200" is output to 

Status-code. 

- - - - - - - - Any code Any status-code is output. 

Note: If possible, do not specify COBW3-CONTENT-TYPE-NON or COBW3-STATUS- 

CODE-NON . "-NON" is meaningful for CGI, which enables Content-type, etc. to be 

specified using a batch file. However, SAF or other DLL applications do not accept - 

NON specification. In addition, operation of SAF is indefinite if Content-type or 

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


COBW3_PUT_HTML 

This subroutine outputs a prototype HTML page for processing the NetCOBOL SAF 

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

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

COBW3_SET_CNV_XX or COBW3_SET_REPEAT_XX subroutine 

Format: 

CALL “COBW3_PUT_HTML” USING COBW3. 


• COBW3-HTML-FILENAME 

Specify the file name of the Web page for processing result output (prototype 

file). 


None. 

Specification of a Conversion Name in the Web Page (prototype file): 

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

is a conversion name. 

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

···//COBOL// Conversion name//COBOL//··· 

Format of the output depends on the conversion name specifications. For example: 

Examples: 

Conversion name specification Processing 

This is a 

If a conversion name "NAME" is specified, 

//COBOL//NAME//COBOL// test. 

"//COBOL//NAME//COBOL//" is converted into a 

registered conversion character string. 

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

result in an error. 

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

This is a //COBOL// 

The conversion name is incorrectly specified (more 

NAME//COBOL// test. 

than one line) 

This is a 

The conversion name is incorrectly specified (second 

//COBOL//NAME//COBOL 

//COBOL//) 

This is a 

//COBOL////COBOL// 

The conversion name is missing, resulting in an error. 

This is a 

This will be output as plain text, due to the incorrect 

//cobol//NAME//cobol// . 

use of lower case in the flags.

Application example: 

[a.htm (Web page prototype file)] 

: 

 

 

Name: //COBOL//GET-NAME//COBOL// 

 

: 

[COBOL program] 


: 

* Specifying a name 

MOVE “GET-NAME” TO COBW3-CNV-NAME. 

MOVE “FUJITSU TARO” TO COBW3-CNV-VALUE. 

* Specifying conversion data to be repeated in the Wed page for 

* processing result output (prototype file) 

CALL “COBW3_SET_CNV” USING COBW3 

: 

* Specifying the file name of the Web page for processing result 

* output (prototype file) 

MOVE “a.htm” TO COBW3-HTML-FILENAME. 

* Outputting the Web page for processing result output (prototype 

* file) 

CALL “COBW3_PUT_HTML” USING COBW3 

: 

[Output result on the WWW browser] 

: 

Name: FUJITSU TARO 

: 

Specification of a Repetition Range in the Web Page Prototype File: 

Write "//COBOL_REPEAT_START//" and "//COBOL_REPEAT_END//" before and after 

a part in the Web page prototype file to specify that the part should be repeated. 

The number of times of repetition is identical to the number of registered repetitive 

character strings to be converted. 

• Beginning of the repetition range 

Write "//COBOL_REPEAT_START//" at the beginning of the range. 

• Repetition data 

Write data to be output repeatedly. If data should be converted when the Web 

application is executed, specify conversion names. 

If a different conversion character string should be output in each separate 

repetition cycle, write "//COBOL_REPEAT//" before and after each conversion 

name. If a separate conversion character string should be output in every 

repetition, write "//COBOL//" before and after conversion name.


• End of the repetition range 

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

repeated. 

Note: Be sure to register each conversion character string corresponding to the 

conversion name enclosed in "//COBOL_REPEAT//" . 

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

data, the number of times of repetition is 1. 

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

Each line containing "//COBOL_REPEAT_START" or "//COBOL_REPEAT_END//"" 

indicating the beginning and end of a repetition range is deleted when data is output 

to the WWW browser. Therefore, do not write anything else on such a line. 

The numbers of repetitive conversion character strings specified in a repetition range 

must match the number of repetitions of the data or an error occurs. 

If the beginning of a repetition range is not specified, data output is not repeated 

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

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

is output and an error occurs. 

//COBOL_REPEAT_START// 

· ·//COBOL_REPEAT// Conversion name//COBOL_REPEAT//· · 

· ·//COBOL// Conversion name// COBOL//· · 

//COBOL_REPEAT_END// 


[b.htm. (Web page for processing result output (prototype file)] 

 

 

Name 

Age 

Company 

 

//COBOL_REPEAT_START// 

 

//COBOL_REPEAT//GET-NAME//COBOL_REPEAT// 

//COBOL_REPEAT//GET-AGE//COBOL_REPEAT// 

//COBOL//GET-OFFICE//COBOL// 

 

//COBOL_REPEAT_END// 

 

:



: 

PERFORM UNTIL END-FLAG=”END” 

* Specifying a name 

MOVE “GET-NAME” TO COBW3-CNV-NAME 

MOVE Name TO COBW3-CNV-VALUE 

* Specifying repetitive conversion data in the Web page for 


CALL “COBW3_SET_REPEAT” USING COBW3 

* Specifying the age 

MOVE “GET-AGE” TO COBW3-CNV-NAME 

MOVE Age TO COBW3-CNV-VALUE 

* Specifying repetitive conversion data in the Web page for 


CALL “COBW3_SET_REPEAT” USING COBW3 

: 

END-PERFORM. 

: 

* Specifying the company name 

MOVE “GET-OFFICE” TO COBW3-CNV-NAME. 

MOVE “FUJITSU” TO COBW3-CNV-VALUE. 

* Specifying conversion data to be repeated in the Web page for 


CALL “COBW3_SET_CNV” USING COBW3. 

: 

* Specifying the file name of the Web page for processing result 

* output (prototype file) 

MOVE “b.htm” TO COBW3-HTML-FILENAME. 

* Outputting the Web page for processing result output (prototype 

* file) 

CALL “COBW3_PUT_HTML” USING COBW3. 

: 

[Output result to the WWW browser] 

: 

Name Age Company 

SUZUKI 35 FUJITSU 

SATO 26 FUJITSU 

TANAKA 23 FUJITSU 

:


COBW3_SET_CNV, COBW3_SET_CNV_XX, 

COBW3_SET_CNV_NX, COBW3_SET_CNV_XN, and 


Each of these subroutines registers a conversion character string corresponding to a 

conversion name enclosed in "//COBOL//" specified in the Web page for processing 

result output (prototype file to be output by the COBW3_PUT_HTML subroutine. The 

appropriate subroutine must be called for each conversion name in the prototype file. 

Registered information is referenced when COBW3_PUT_HTML is executed, and data 

in the Web page for processing result output (prototype file) is converted according 

to the registered conversion data. 

These subroutines have the following meanings. 


• COBW3_SET_CNV 

Registers a conversion character string corresponding to the conversion name of 

an alphanumeric character string as an alphanumeric character string. 


• COBW3_SET_CNV_XX 

Registers a conversion character string corresponding to the conversion nameof 

an alphanumeric character string as an alphanumeric character string. 

• COBW3_SET_CNV_NX 


a national character string as an alphanumeric character string. 

• COBW3_SET_CNV_XN 


an alphanumeric character string as a national character string. 

• COBW3_SET_CNV_NN 


a national character string as a national character string. 

Format: 

CALL "COBW3_SET_CNV" USING COBW3. 

CALL "COBW3_SET_CNV_XX" USING COBW3. 

CALL "COBW3_SET_CNV_NX" USING COBW3. 

CALL "COBW3_SET_CNV_XN" USING COBW3.

CALL "COBW3_SET_CNV_NN" USING COBW3. 



• COBW3-CNV-NAME and COBW3-CNV-NAME-N 

Set a conversion name used for conversion. 

Set it in COBW3-CNV-NAME when COBW3_SET_CNV, COBW3_SET_CNV_XX or 

COBW3_SET_CNV_XN is used. 

Set a conversion name in COBW3-CNV-NAME-N when COBW3_SET_CNV_NX or 

COBW3_SET_CNV_NN is used. 

• COBW3-CNV-NAME-LENGTH [Optional] 

Set the character length of a conversion name with a valid space at the end to 

the number of bytes including the space. 

• 

• 

Value Meaning 

0 The length to the last character, excluding the space, is checked. However, 

the character length is regarded as 0 if COBW3-CNV-NAME or COBW3-CNV- 

NAME-N is filled with spaces only. 

1 to 30 Character strings of the specified character length are searched for. 

COBW3-CNV-VALUE and COBW3-CNV-VALUE-N 

Set the conversion result (conversion character string). 

Set it in COBW3-CNV-VALUE when COBW3_SET_CNV, COBW3_SET_CNV_XX or 

COBW3_SET_CNV_NX is used. 

Set it in COBW3-CNV-VALUE-N when COBW3_SET_CNV_XN or 


COBW3-CNV-VALUE-LENGTH [Optional] 

Set the character length of a conversion character string with a valid space at the 

end in the number of bytes including the space. 

Value Meaning 

0 The length to the last character, excluding the space, is registered. However, 

the character length is regarded as 0 if COBW3-CNV-VALUE or COBW3-CNV- 

VALUE-N is filled with spaces only. 

1 to 1024 Character strings of the specified character length are searched for.


• COBW3-CNV-MODE [Optional] 

Set a conversion type. 


COBW3-CNV-MODE 

–ADDREP 


–REPLACE 


–ADD 

LOW-VALUE The conversion data is added if the specified 

conversion name is not registered. 

“1” Data is converted. If the specified conversion 

name is not registered, an error is output and 

data is not converted. 

“2” The conversion data is added. If the specified 

conversion name is registered, an error is 

output and data is not added. 

• COBW3_SANITIZE_CNV [Optional] 

If characters that are vulnerable to a cross site scripting attack are found in 

conversion data, those characters are automatically replaced. This process is referred 

to as “sanitizing”. 

For more details on cross site scripting, refer to Appendix P, Security, in the 

NetCOBOL User’s Guide. 

COBW3_SANITIZE_CNV is valid when either COBW3_SET_CNV_XX or 

COBW3_SET_CNV_NX is used. However, if the code set is Unicode, 

COBW3_SANITIZE_CNV is also valid when COBW3_SET_CNV_XN or 


Condition name Value Explanation 

COBW3-SANITIZE-CNV-OFF LOW-VALUE Does not sanitize. 

COBW3-SANITIZE-CNV-ON "1" Sanitize. 

NOTE: 

The sanitization procedure replaces the five characters that are vulnerable to a cross 

site scripting attack (&, , “, ‘) with the following escape characters: 

& → & 

< → < 

> → > 

" → " 

' → ' 

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

length of the sanitized data. This means that, depending on the content of the 

unsanitized data, sanitizing data may cause the maximum data length (1024 bytes) 

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

is truncated automatically at 1024 bytes. 

It is also possible that the escape characters themselves may be truncated. In this 

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


Example: The unsanitized data area is 1021 bytes long. The first 1020 bytes 

contain n characters that do not require sanitizing, but the last character is an 

ampersand ( & ). 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&


Format: 

CALL "COBW3_DEL_CNV" USING COBW3. 

CALL "COBW3_DEL_CNV_X" USING COBW3. 

CALL "COBW3_DEL_CNV_N" USING COBW3. 



Set a conversion name to be deleted. 

Set it in COBW3-CNV-NAME when COBW3_DEL_CNV or COBW3_DEL_CNV_X is 

used. 

Set it in COBW3-CNV-NAME-N when COBW3_DEL_CNV_N is used. 

• 

COBW3-CNV-NAME-LENGTH [Optional] 



Value Meaning 

0 The length to the last character, excluding the space, is checked. However, the 

character length is regarded as 0 if COBW3-CNV-NAME or COBW3-CNV-NAME-N 

is filled with spaces only. 



None 

COBW3_INIT_CNV 

This subroutine initializes all conversion data specified using COBW3_SET_CNV_XX or 

other subroutines. 

Format: 

CALL "COBW3_INIT_CNV" USING COBW3. 


None 


None


COBW3_SET_REPEAT, COBW3_SET_REPEAT_XX, 

COBW3_SET_REPEAT_NX, COBW3_SET_REPEAT_XN, and 

COBW3_SET_REPEAT_NN 

Each of these subroutines registers the repetitive conversion data of a conversion 

name enclosed in "//COBOL_REPEAT//" specified in a Web page for processing result 

output (prototype file) to be output by the "COBW3_PUT_HTML" subroutine. 

Registered information is referenced when COBW3_PUT_HTML is executed. The 

conversion name specified in the repetition range in the Web page for processing 

result output (prototype file) is converted according to the number of repetitive 

conversion character strings registered for the same conversion name. 

Each subroutine has the following meaning: 


• COBW3_SET_REPEAT 

Registers the conversion character string corresponding to an alphanumeric 

character string conversion name as an alphanumeric character string. 


• COBW3_SET_REPEAT_XX 


character string conversion name as an alphanumeric character string. 

• 

• 

COBW3_SET_REPEAT_NX 

Registers the conversion character string corresponding to a national character 

string conversion name as an alphanumeric character string. 

COBW3_SET_REPEAT_XN 


character string conversion name as a national character string. 

• COBW3_SET_REPEAT_NN 

Registers the conversion character string corresponding to a national character 

string conversion name as a national character string. 

Note: Register a repetitive conversion character string for each conversion name by 

calling "COBW3_SET_REPEAT_XX" or other subroutines. 

The conversion character strings are converted in repetitive conversion in the order 

of registration using "COBW3_SET_REPEAT_XX" or other subroutines. 

Specify the same number repetitive conversion character strings as conversion 

names in the same repetition range. 

Format: 

CALL "COBW3_SET_REPEAT" USING COBW3. 

CALL "COBW3_SET_REPEAT_XX" USING COBW3.


CALL "COBW3_SET_REPEAT_NX" USING COBW3. 

CALL "COBW3_SET_REPEAT_XN" USING COBW3. 

CALL "COBW3_SET_REPEAT_NN" USING COBW3. 



Set a conversion name used for conversion. 

Set it in COBW3-CNV-NAME when COBW3_SET_REPEAT, 

COBW3_SET_REPEAT_XX or COBW3_SET_REPEAT_XN is used. 

• 

• 

• 

Set it in COBW3-CNV-NAME-N when COBW3_SET_REPEAT_NX or 

COBW3_SET_REPEAT_NN is used. 




Value Meaning 

0 The length up to the last character, excluding the space, is checked. However, 



1 to 30 Character strings of the specified character length are searched for 

COBW3-CNV-VALUE and COBW3-CNV-VALUE-N 

Set a conversion result (conversion character string). 

Set it in COBW3-CNV-VALUE when COBW3_SET_REPEAT, 

COBW3_SET_REPEAT_XX or COBW3_SET_REPEAT_NX is used. 

Set it in COBW3-CNV-VALUE-N when COBW3_SET_REPEAT_XN or 

COBW3_SET_REPEAT_NN is used. 

COBW3-CNV-VALUE-LENGTH [Optional] 


end to the number of bytes including the space. 

Value Meaning 

0 The length to the last character, excluding the space, is registered. However, 

the character length is regarded as 0 if COBW3-CNV-VALUE or COBW3-CNV- 

VALUE-N is filled with spaces only. 


Specify a space as the conversion character string, 0 as the conversion character 

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

as the conversion result.

• COBW3_SANITIZE_CNV [Optional] 


If characters that are vulnerable to a cross site scripting attack are found in 

conversion data, those characters are automatically replaced. This process is referred 

to as “sanitizing”. 

For more details on cross site scripting, refer to Appendix P, Security, in the 

NetCOBOL User’s Guide. 

COBW3_SANITIZE_CNV is valid when either COBW3_SET_REPEAT_XX or 

COBW3_SET_ REPEAT_NX is used. However, if the code set is Unicode, 

COBW3_SANITIZE_CNV is also valid when COBW3_SET_ REPEAT_XN or 

COBW3_SET_ REPEAT_NN is used. 

Condition name Value Explanation 

COBW3-SANITIZE-CNV-OFF LOW-VALUE Does not sanitize. 

COBW3-SANITIZE-CNV-ON "1" Sanitize. 

NOTE: 

The sanitization procedure replaces the five characters that are vulnerable to a cross 

site scripting attack (&, , “, ‘) with the following escape characters: 

& → & 

< → < 

> → > 

" → " 

' → ' 

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

length of the sanitized data. This means that, depending on the content of the 

unsanitized data, sanitizing data may cause the maximum data length (1024 bytes) 

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

is truncated automatically at 1024 bytes. 

It is also possible that the escape characters themselves may be truncated. In this 

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

Example: The unsanitized data area is 1021 bytes long. The first 1020 bytes 

contain n characters that do not require sanitizing, but the last character is an 

ampersand ( & ). 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&


This exceeds the 1024-byte limit, but truncating the data to 1024 bytes would 

interrupt the escape character string (&). For this reason, the ampersand is 

deleted instead of being replaced. 

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Format: 

CALL "COBW3_DEL_REPEAT" USING COBW3. 

CALL "COBW3_DEL_REPEAT_X" USING COBW3. 

CALL "COBW3_DEL_REPEAT_N" USING COBW3. 



Set a conversion name to be deleted. 

Set it in COBW3-CNV-NAME when COBW3_DEL_REPEAT or 

COBW3_DEL_REPEAT_X is used. 

• 


Set it in COBW3-CNV-NAME-N when COBW3_DEL_REPEAT_N is used. 



end to the number of bytes including the space. 

Value Meaning 

0 The length to the last character, excluding the space, is checked. However, 





None


COBW3_INIT_REPEAT 

This subroutine initializes all repetitive conversion data specified using 

COBW3_SET_REPEAT_XX or other subroutine. 

Format: 

CALL "COBW3_INIT_REPEAT" USING COBW3. 


None 


None 

COBW3_PUT_TEXT 

This subroutine outputs a specified character string and a line feed character to the 

WWW browser. 

Format: 

CALL "COBW3_PUT_TEXT" USING COBW3. 


• COBW3-PUT-STRING 

Set a character string to be output. 

• COBW3-PUT-STRING-LENGTH [Optional] 

Set the character length of a character string with a valid space at the end to the 

number of bytes including the space. 

Value Meaning 

0 Character strings of any length, excluding the space, are output. 

However, the character length is regarded as 0 (i.e., line feed 

character only) if COBW3-PUT-STRING is filled with spaces only. 

1 to 1024 Character strings of the specified character length are output. 


None 

Outputting Character String Data (including a line feed character) to the 

WWW Browser: 

The following example shows how to output " Thank you for your 

cooperation. " to the WWW browser.




: 

00036 * Setting the character string to be output 

00037 MOVE “ Thank you for your cooperation.” 

00038 TO COBW3-PUT-STRING. 

00039 * Outputting the character string data 

00040 CALL “COBW3_PUT_TEXT” USING COBW3. 

: 

[Output result on the WWW browser] 

: 

Thank you for your cooperation. 

: 

Execute System Commands 

COBW3_SYSTEM 

This subroutine executes a system command from the Web application. 

Format: 

CALL "COBW3_SYSTEM" USING COBW3. 


• COBW3-SYSTEMINFO 

Set a system command to be executed and its parameters. 


None 

Note: Due to the extreme risk to the integrity of the operating system, we 

recommend that you never create a web application that permits execution of a 

command string input to the browser. 

Free SAF Execution Environment Resources 

COBW3_ FREE 

This subroutine frees resources obtained by a SAF subroutine. To prevent 

exhaustion of system resources, call this subroutine at the end of every connection 

of the Web application. 

Format: 



None



None 

Get Request Information 

COBW3_RECEIVE_HEADER 

This subroutine acquires the HTTP header of a request. 

Format: 

CALL "COBW3_RECEIVE_HEADER" USING COBW3. 


• COBW3-HEADER-NAME 

• 

Set a header name to be acquired. 

COBW3-HEADER-NAME-LENGTH [Optional] 

Set the character length of a header name with a valid space at the end to the 

number of bytes including the space. 

Value Meaning 

0 The length to the last character, excluding the space, is checked. 

1 to 64 Header names of the specified character length are searched for. 

Note: Specify 0 since header names normally have no spaces at the end. 


• 

• 

COBW3-HEADER-VALUE 

The header value corresponding to the requested header name is set. 

COBW3-HEADER-VALUE-LENGTH 

The character length (byte length) of the header value corresponding to the 

requested header name is set. 

COBW3_GET_REQUEST_INFO 

This subroutine acquires information concerning a request. 

CALL "COBW3_GET_REQUEST_INFO" USING COBW3. 


• COBW3-REQUEST-INFO-TYPE 

Specify the information to be acquired:


COBW3-URI LOW-VALUE Request URI 


COBW3-URL “1” Request URL 

COBW3-SERVER-TYPE 

(COBW3-LISTENERTYPE) 

“2” Server type 

COBW3-VIRTUALPATH “3” Virtual path name of a request 

COBW3-PHYSICALPATH “4” Physical path name corresponding to the 

virtual path of a request 

COBW3-QUERYSTRING “5” Web parameter 

COBW3-LANGUAGE “6” List of languages which the WWW browser 

can receive 

COBW3-ENCODING “7” List of encoding which the WWW browser 

can receive 

COBW3-REQMIMETYPE “8” MIME type of a request 

COBW3-REQUEST- 

METHOD 

“9” Request method 

COBW3-PATH-INFO “A” Extended path name sent by the WWW 

browser 

COBW3-PATH- 

TRANSLATED 

“B” Physical path name corresponding to the 

extended path 

COBW3-REMOTE-ADDR “C” IP address of the client 

COBW3-REMOTE-HOST “D” Host name of the client 

COBW3-GATEWAY 

–INTERFACE 

“E” Revision of the support CGI 

COBW3-SERVER-NAME “F” Host name of the server 

COBW3-SERVER-PORT “G” Connection port No. of the server 

COBW3-SERVER 

–PROTOCOL 

“H” Protocol used by the server 

COBW3-SERVER-PORT “I” "1" is returned during secure 

–SECURE 

communication. "0" is returned otherwise. 

Note: No server type may be acquired. 

If the extended path is specified, it may be impossible to acquire correct request 

URI, request URL, MIME type of the request, virtual path name of the request, and 

physical path name corresponding to the virtual path of a request. 


• COBW3-REQUEST-INFO 

Acquired request information is set. 

• COBW3-REQUEST-INFO-LENGTH 

The character length (byte length) of the acquired request information is set.


COBW3_GET_AUTHORIZE 

This subroutine acquires authorization information from the WWW browser. The 

authorization information includes the ID and password of the user and the IP 

address of the client. 

Format: 

CALL "COBW3_GET_AUTHORIZE" USING COBW3. 


None 


• 

• 

• 

• 

• 

• 

COBW3-USERID 

The acquired user ID is set. 

COBW3-USERID-LENGTH 

The character length (byte length) of the user ID is set. 

COBW3-PASSWORD 

The acquired user password is set. 

COBW3-PASSWORD-LENGTH 

The character length (byte length) of the user password is set. 

COBW3-IP-ADDRESS 

The acquired client IP address is set. 

COBW3-IP-ADDRESS-LENGTH 

The character length (byte length) of the IP address is set. 

• COBW3-AUTH-TYPE 

The acquired authorization type is set. 

• COBW3-AUTH-TYPE-LENGTH 

The character length (byte length) of the authorization type is set. 

Note: This subroutine cannot acquire any information of an anonymous 

authorization except the IP address. 

It may acquire any type of information of a basic authorization. "basic" is set as the 

authorization type.

Manipulate Cookie Data 


COBW3_SET_COOKIE, COBW3_SET_COOKIE_XX, 

COBW3_SET_COOKIE_NX, COBW3_SET_COOKIE_XN, 


Register the Cookie data to be sent to the WWW browser. The registered Cookie 

data is used for header output. 

Each subroutine has the following meaning. 


• COBW3_SET_COOKIE 

Registers the alphanumeric Cookie name and the corresponding Cookie value as 

an alphanumeric character string. 


• COBW3_SET_COOKIE_XX 


an alphanumeric character string. 

• 

• 

• 

COBW3_SET_COOKIE_NX 

Registers the national character Cookie name and the corresponding Cookie 

value as an alphanumeric character string. 

COBW3_SET_COOKIE_XN 


a national character string. 


Registers the national character Cookie name and the corresponding Cookie 

value as a national character string. 

Note: Use this subroutine before calling COBW3_PUT_HTML or COBW3_PUT_TEXT. 

The Cookie character code sent to the WWW browser is always ASCII regardless of 

the COBOL operation code system. 

Formats: 

CALL "COBW3_SET_COOKIE" USING COBW3. 

CALL "COBW3_SET_COOKIE_XX" USING COBW3. 

CALL "COBW3_SET_COOKIE_NX" USING COBW3. 

CALL "COBW3_SET_COOKIE_XN" USING COBW3.


CALL "COBW3_SET_COOKIE_NN" USING COBW3. 

Data setup during call: 

• COBW3-COOKIE-NAME, COBW3-COOKIE-NAME-N 

Sets a Cookie name you wish to register. 

Specify “COBW3-COOKIE-NAME” for the COBW3_SET_COOKIE, 

COBW3_SET_COOKIE_XX or COBW3_SET_COOKIE_XN. Specify “COBW3- 

COOKIE-NAME-N” for the COBW3_SET_COOKIE_NX or 

COBW3_SET_COOKIE_NN. 

• COBW3-COOKIE-NAME-LENGTH [Optional] 

Sets the length of Cookie name character string (in bytes) including spaces if the 

Cookie name has a valid space at the end . 

• 

• 

Value Meaning 

0 Registers the Cookie name consisting of a character string including the last 

character except for a space. However, if the COBW3_COOKIE-NAME or 

COBW3_COOKIE-NAME-N consists of only spaces, the length of character string 

is considered to be zero (0). 

1 to 64 Register the Cookie name consisting of the specified number of characters. 

COBW3-COOKIE-VALUE, COBW3-COOKIE-VALUE-N 

Set a Cookie value. 

Specify “COBW3-COOKIE-VALUE” for COBW3_SET_COOKIE, 

COBW3_SET_COOKIE_XX or for COBW3_SET_COOKIE_NX. 

Also, set “COBW3-COOKIE-VALUE-N” for COBW3_SET_COOKIE_XN or 

COBW3_SET_COOKIE_NN. 

COBW3-COOKIE-VALUE-LENGTH [Optional] 

Sets the length of the Cookie value character string (in bytes) including spaces if 

a Cookie value having a valid space at its end is specified. 

Value Meaning 

0 Registers a Cookie value consisting of a character string including the last 

character except for a space. However, if the COBW3-COOKIE-VALUE or 

COBW3-COOKIE-VALUE-N contains of only spaces, the length of character 

string is considered to be zero (0). 

1 to 1024 Register a Cookie value consisting of the specified number of characters. 

• COBW3-COOKIE-EXPIRES [Optional] 

Use this subroutine to specify the Cookie expiration date. The expiration time 

must be set in Greenwich Mean Time (GMT). 

- COBW3-COOKIE-EXPIRES-YEAR (Year) (1582 to 9999) 

- COBW3-COOKIE-EXPIRES-MONTH (Month) (01 to 12) 

- COBW3-COOKIE-EXPIRES-DAY (Day) (01 to 31; with the last day depending 

on the month)

- COBW3-COOKIE-EXPIRES-HOUR (Hours) (00 to 23) 

- COBW3-COOKIE-EXPIRES-MIN (Minutes) (00 to 59) 

- COBW3-COOKIE-EXPIRES-SEC (Seconds) (00 to 59) 


Note: If the expiration date is omitted, the Cookie data is deleted when the browser 

is terminated. The Cookie data that the browser currently has is deleted immediately 

if a clock time is specified that is already past. 

Specify an expiration date after October 15th of 1582. If you specify an earlier date 

, the expiration date is will not be correctly set, due to failure of the automatic day of 

week calculation. 

• 

• 

• 

COBW3-COOKIE-DOMAIN [Optional] 

Sets a domain where the Cookie is valid. 

COBW3-COOKIE-PATH [Optional] 

Sets a virtual path where the Cookie is valid. 

COBW3-COOKIE-SECURE [Optional] 

Sets the security. If the security is on, the Cookie data is sent from the WWW 

browser only when SSL is used. 


COBW3-COOKIE 

-SECURE-OFF 

LOW-VALUE Allow any method to transport the cookie 

COBW3-COOKIE 

-SECURE-ON 

“1” Allow only SSL to transport the cookie 

• COBW3-COOKIEMODE [Optional] 

Sets a registration type of Cookie data. 


COBW3-COOKIE 

–MODE-ADDREP 

COBW3-COOKIE 

–MODE-REPLACE 

COBW3-COOKIE 

–MODE-ADD 

Process Result Data: 

None 

LOW-VALUE Adds Cookie data if the specified Cookie name is 

not registered. 

“1” Replaces the Cookie data. If the specified Cookie 

name is not registered, an error is output and the 

name is not registered. 

“2” Adds Cookie data. If the specified Cookie name is 

already registered, an error is output and the data 

is not added.


COBW3_DEL_COOKIE, COBW3_DEL_COOKIE_X, 

COBW3_DEL_COOKIE_ N 

Delete Cookie data which has been registered by COBW3_SET_COOKIE_XX or 

others. 



• COBW3_DEL_COOKIE 

Deletes the Cookie data corresponding to the alphanumeric Cookie name. 


• COBW3_DEL_COOKIE_X 

Deletes the Cookie data corresponding to the alphanumeric Cookie name. 

• COBW3_DEL_COOKIE_N 

Deletes the Cookie data corresponding to the national character Cookie name. 


Formats: 

CALL "COBW3_DEL_COOKIE" USING COBW3. 

CALL "COBW3_DEL_COOKIE_X" USING COBW3. 

CALL "COBW3_DEL_COOKIE_N" USING COBW3. 



Sets a Cookie name to be deleted. 

Specify “COBW3-COOKIE-NAME” for the COBW3_DEL_COOKIE or 

COBW3_DEL_COOKIE_X. 

• 

Also, specify “COBW3-COOKIE-NAME-N” for the COBW3_DEL_COOKIE_N. 

COBW3-COOKIE-NAME-LENGTH [Optional] 

Sets the length of Cookie name character string (in bytes) containing spaces if a 

Cookie name having a valid space at its end is specified. 

Value Meaning 

0 Deletes up to the end of character string except for a space. However, if the 

COBW3-COOKIE-NAME or COBW3-COOKIE-NAME-N consists of only spaces, the 

length of character string is considered to be zero (0). 

1 to 64 Deletes the specified length of character string.

Process result data: 

None 

COBW3_INIT_COOKIE 


Initializes the Cookie data that has been registered by the COBW3_SET_COOKIE_XX 

or others. 


Format: 

CALL "COBW3_INIT_COOKIE" USING COBW3. 

Data setup during call: 

• COBW3-COOKIE-INIT-MODE [Optional] 

Sets an initialization type of Cookie data. 


COBW3-COOKIE 

–INIT-MODE-NORMAL 

LOW-VALUE Initializes all Cookie data. 

COBW3-COOKIE 

“1” Initializes the requested Cookie data to the 

–INIT-MODE-REQUEST 

initial value. 


None 

COBW3_GET_COOKIE, COBW3_GET_COOKIE_XX, 

COBW3_GET_COOKIE_NX, COBW3_GET_COOKIE_XN, 


Search any Cookie name in the requested Cookie data collected by the 

“COBW3_INIT.” Each subroutine has the following meaning. 


• COBW3_GET_COOKIE 

Searches for a Cookie name consisting of an alphanumeric character string, and 

returns the corresponding Cookie value in an alphanumeric character string. 


• COBW3_GET_COOKIE_XX 

Searches a Cookie name consisting of an alphanumeric character string, and 

returns the corresponding Cookie value in an alphanumeric character string. 

• COBW3_GET_COOKIE_NX 

Searches a Cookie name consisting of a national character string, and returns the 

corresponding Cookie value in an alphanumeric character string.


• 

• 

COBW3_GET_COOKIE_XN 

Searches a Cookie name consisting of an alphanumeric character string, and 

returns the corresponding Cookie value in a national character string. 


Searches a Cookie name consisting of a national character string, and returns the 

corresponding Cookie value in a national character string. 

When the collected Cookie value is stored, it is padded with blanks. 

Format: 

CALL "COBW3_GET_COOKIE" USING COBW3. 

CALL "COBW3_GET_COOKIE_XX" USING COBW3. 

CALL "COBW3_GET_COOKIE_NX" USING COBW3. 

CALL "COBW3_GET_COOKIE_XN" USING COBW3. 

CALL "COBW3_GET_COOKIE_NN" USING COBW3. 



Sets a Cookie name to be searched. 

Set a Cookie name in COBW3-COOKIE-NAME for COBW3_GET_COOKIE, 

COBW3_GET_COOKIE_XX or COBW3_GET_COOKIE_XN. Set a Cookie name in 

COBW3-COOKIE-NAME-N for COBW3_GET_COOKIE_NX or 

COBW3_GET_COOKIE_NN. 

• COBW3-COOKIE-NAME-LENGTH [Optional] 

Sets the length of Cookie name character string (in bytes) containing spaces to 

search a Cookie name which ends with a valid space. 

Value Meaning 

0 Searches a Cookie name of the entire character string except for spaces. 

However, if the COBW3-COOKIE-NAME or COBW3-COOKIE-NAME-N consists of 

only spaces, the length of character string is considered to be zero. 

1 to 64 Searches a Cookie name in the specified length of character string.



• 

• 



COBW3-SEARCH-FLAG–NON “0” The specified name is not found. 

COBW3-SEARCH–FLAG-EXIST “1” The specified name has been found. 

COBW3-COOKIE-VALUE, COBW3-COOKIE-VALUE-N 

Set a Cookie value corresponding to the Cookie name to be searched. 

The Cookie value is set in COBW3-COOKIE-VALUE for COBW3_GET_COOKIE, 

COBW3_GET_COOKIE_XX or COBW3_GET_COOKIE_NX. 

It is set in COBW3-COOKIE-VALUE-N for COBW3_GET_COOKIE_XN or 

COBW3_GET_COOKIE_NN. 

COBW3-COOKIE-VALUE-LENGTH 

Sets the length of Cookie value character string (in bytes) corresponding to the 

Cookie name to be searched. 

Manipulate Uploaded Files 

COBW3_GET_UPLOADFILE_INFO,COBW3_GET_UPLOADFILE_ 

INFO_X and COBW3_GET_UPLOADFILE_INFO_N 

These subroutines acquire the information on an uploaded file. Details of these 

subroutines are as follows: 

ASCII environment 

• COBW3_GET_UPLOADFILE_INFO 

Retrieves the name of the uploaded file (alphanumeric character string specified 

in NAME), and acquires the information about the found uploaded file. 

Unicode environment 

• 

• 

COBW3_GET_UPLOADFILE_INFO_X 

Retrieves the name of the uploaded file (alphanumeric character string specified 

in NAME), and acquires the information about the found uploaded file. 

COBW3_GET_UPLOADFILE_INFO_N 

Retrieves the name of the uploaded file (national language character strings 

specified in NAME), and acquires the information about the found uploaded file. 

Format: 

CALL "COBW3_GET_UPLOADFILE_INFO" USING COBW3. 

CALL "COBW3_GET_UPLOADFILE_INFO_X" USING COBW3.


CALL "COBW3_GET_UPLOADFILE_INFO_N" USING COBW3. 

Data setting for calling: 


Set the name (NAME) of the upload file to be retrieved (The name specified in 

“name” of the HTML document (Web page for invoking application) must be set 

instead of the file name). 

For COBW3_GET_UPLOADFILE_INFO and COBW3_GET_UPLOADFILE_INFO_X, 

set the name to COBW3-SEARCH-DATA. 

• 

For COBW3_GET_UPLOADFILE_INFO_N, set the name to COBW3-SEARCH- 

DATA-N. 

COBW3-SEARCH-LENGTH [optional] 

If the name (NAME) has a valid blank at the end, set the string length (byte 

length) of the name including the blank. 

Value Meaning 

0 Searches the upload file name using the length up to the last character 

excluding the blank. However, if COBW3-SEARCH-DATA or COBW3-SEARCH- 

DATA-N is completely blank, the string length is set to zero for processing. 

1 to 1024 Searches the upload file name using the specified string length. 

• COBW3-NUMBER [optional] 

If multiple entities with the same name (NAME) exist in Web parameters, set the 

order of appearance of names to be searched. 

Condition name Value Meaning 

COBW3-NUMBER-INIT 1 Searches the name that matches first. 

- - - - - - - - - - 2 to 9999 Searches the names in the specified order of 

appearance. 



• 

• 


COBW3-SEARCH-FLAG-NON "0" The name to be searched does not exist, or 

size of the uploaded file is 0. 

COBW3-SEARCH-FLAG-EXIST "1" The name to be searched exists. 

COBW3-UPLD-CL-FILE-PATH 

Sets the path name of the upload file in the client which corresponds to the 

retrieved name (NAME). 

COBW3-UPLD-CL-FILE-PATH-LENGTH 

Sets the character string length (byte length) of the path name of the upload file 

in the client which corresponds to the retrieved name (NAME).

• 

• 

• 

• 


COBW3-UPLD-CL-FILE-NAME 

Sets the file name of the upload file in the client which corresponds to the 

retrieved name (NAME). 

COBW3-UPLD-CL-FILE-NAME-LENGTH 

Sets the character string length (byte length) of the file name of the upload file 

in the client which corresponds to the retrieved name (NAME). 

COBW3-UPLD-CONTENT-TYPE 

Sets the character string that indicates the Content-type of the upload file that 

corresponds to the retrieved name (NAME). 

COBW3-UPLD-CONTENT-TYPE-LENGTH 

Sets the character string length (byte length) of the character string that 

indicates the content type of the upload file that corresponds to the retrieved 

name (NAME). 

• COBW3-UPLD-FILE-SIZE 

Sets the uploaded file size (byte length) . 

Note: When “\” is included in the uploaded file name when the client is UNIX, the 

file name and the path name cannot be correctly received. 

Example: 

[c.htm (Web page for invoking application)] 

: 

 

 

Your Name: 

Send file 1: 

 

 

 

: 

[COBOL source program] 

: 

* Name setup 

MOVE "FILE1" TO COBW3-SEARCH-DATA. 

* Acquisition of upload file information 

CALL "COBW3_GET_UPLOADFILE_INFO_X" USING COBW3. 

: 

IF COBW3-SEARCH-FLAG-EXIST THEN 

* Setup of name of file to be generated 

MOVE "d.tmp" TO COBW3-UPLOADED-FILENAME 

* File generation 

CALL "COBW3_GEN_UPLOADFILE_X" USING COBW3 

: 

* File data processing 

: 

* Deletion of generated file 

CALL "COBW3_DEL_UPLOADEDFILE" USING COBW3 

END-IF. 

:


COBW3_GEN_UPLOADFILE, COBW3_GEN_UPLOADFILE_X and 

COBW3_GEN_UPLOADFILE_N 

These subroutines generate an uploaded file by using a specified file name. The 

details of these subroutines are as follows: 

ASCII environment 

• COBW3_GEN_UPLOADFILEX 

Searches the name (NAME) of an alphanumeric character string, and generates 

the found uploaded file by using the specified file name. 

Unicode environment 

• COBW3_GEN_UPLOADFILE_X 

Searches the name (NAME) of an alphanumeric character string, and generates 

the found uploaded file by using the specified file name. 

• COBW3_GEN_UPLOADFILE_N 

Searches the name (NAME) of a national character string, and generates the 

found uploaded file by using the specified file name. 

Note: Uploaded files must not be generated as executable files because of the 

threat to security. Especially, uploaded files must not be generated as files that can 

be automatically executed by the system. 

Format: 

CALL "COBW3_GEN_UPLOADFILE" USING COBW3. 

CALL " COBW3_GEN_UPLOADFILE_X" USING COBW3. 

CALL " COBW3_GEN_UPLOADFILE_N" USING COBW3. 



Set the name (NAME) of the uploaded file to be searched (The name specified 

in “name” of the HTML document [Web page for invoking application] must be 

set instead of the file name). 

For COBW3_GEN_UPLOADFILE and COBW3_GEN_UPLOADFILE_X, set the name 

to COBW3-SEARCH-DATA. 

For COBW3_GEN_UPLOADFILE_N, set the name to COBW3-SEARCH-DATA-N. 

• COBW3-SEARCH-LENGTH [optional] 

If the value (VALUE) has a valid blank at the end, set the string length (byte 

length) of the value including the blank.

Value Meaning 


0 Searches the name using the length up to the last character excluding the 

blank. 

1 to 1024 Searches the name using the specified string length. 

• COBW3-NUMBER [optional] 

Sets the order of appearance of NAMES to be searched when there are multiple 

NAMES with the same name in the Web parameters. 


COBW3-NUMBER-INIT 1 Searches the name that matches first. 

- - - - - - - - - - 2 to Searches the name in the specified order of 

9999 appearance. 

• COBW3-UPLOADED-FILENAME 

Specify the name of the file to be generated on the server. 




COBW3-SEARCH-FLAG-NON "0" The name to be searched does not exist. 

COBW3-SEARCH-FLAG-EXIST "1" The name to be searched exists. 

COBW3_DEL_UPLOADFILE 

This subroutine deletes an uploaded file that was generated using a subroutine such 

as COBW3_GEN_UPLOADFILE. 

This subroutine can delete a file that was generated using 

COBW3_GEN_UPLOADFILE, COBW3_GEN_UPLOADFILE_X or 

COBW3_GEN_UPLOADFILE_N within the same request. File generation or deletion 

among two or more requests (two or more pages) cannot be performed. 

Format: 

CALL "COBW3_DEL_UPLOADFILE" USING COBW3. 


• COBW3-UPLOADED-FILENAME 

Set the name of the file to be deleted. 


None


Manage Sessions 

COBW3_START_SESSION 

Starts a session. Also, it sets a data type and timeout value for the session. 

Notes: Call this subroutine before using the “COBW3_PUT_TEXT,” 

“COBW3_PUT_HTML” or “COBW3_FREE.” Once any of these subroutines is used, no 

session can be started even when the COBW3_START_SESSION subroutine is called. 

If a session has already been started, an error is returned when this subroutine is 

called. 

The data type cannot be changed after a session is established. To change the data 

format, terminate the session by calling the “COBW3_END_SESSION” And then start 

a new session. 

Format: 

CALL "COBW3_START_SESSION " USING COBW3. 


• COBW3-SESSION-DATA-TYPE 

Sets a session data type. 


COBW3–SESSION-DATA-GROUPITEM “0” Uses a group item as the session 

data. 

COBW3-SESSION–DATA-OBJECT “1” Uses an object reference item as the 

session data. 

• COBW3-SESSION-TIMEOUT 

Specifies a session timeout (in seconds). This is the maximum waiting period 

allowed, from the time when “COBW3_FREE” is called to the time when 

“COBW3_INIT” is called in the next thread of the same session, before 

automatic session termination occurs. 

Value Meaning 

1 to 999999 Timeout processing is executed when the specified time (in seconds) has 

passed. 


None

COBW3_END_SESSION 


Terminates the current session. Also, it deletes information set during session 

establishment. 

Notes: Call this subroutine before using the “COBW3_PUT_TEXT,” 

“COBW3_PUT_HTML” or “COBW3_FREE.” Once any of these subroutines is used, no 

session can be terminated even if the COBW3_END_SESSION subroutine is called. 

If the session has already been terminated, an error is returned when this subroutine 

is called. 

Formats: 

CALL "COBW3_END_SESSION " USING COBW3. 


None 


None 

COBW3_SET_SESSION_DATA 

Registers session data to be used in the current session. The registered data is 

shared within the same session. 

Note: Call this subroutine when the session has been established. No session data 

can be registered if it is called before or after the session. 

The session data format cannot be changed when a session is established. 

Formats: 

CALL "COBW3_SET_SESSION_DATA" USING COBW3 session-data 


• COBW3-SESSION-DATA-SIZE 

Specifies a session data length (in bytes). It is valid only if the COBW3- 

SESSION-DATA-GROUPITEM has been set in the session data format during 

session startup. 

Value Meaning 

1 to 999999999 Registers a session data in the specified length (in bytes). 

• Session data 

Specifies session data to be registered. It can be a group item or an object 

reference item, depending on the session data format. 

Notes: When specifying a group item in the session data, you cannot specify an 

object reference item or pointer data item as a subordinate elementary item.


When an object reference item is specified in the session data, the object class 

identified by the object reference item must inherit the COBW3-SESSION-ADAPTER 

class. 

If you have specified an object reference item in the session data, always assign a 

NULL object to the object reference item before its thread ends. If the NULL object 

is not assigned, the object may remain in memory after the session has ended. This 

may cause a memory shortage. 

If the session data to be registered differs from the session data format which has 

been set during session startup, the Web application operations are unreliable. 


None 

COBW3_GET_SESSION_DATA 

Gets session data registered in the current session. 

Notes: Call this subroutine when the session is established. No session data can be 

obtained if this subroutine is called before startup of a session or after the end of the 

session. 

The session data format cannot be changed after the session is established. 

Format: 

CALL "COBW3_GET_SESSION_DATA" USING COBW3 session-data 



Specifies a group item length (in bytes) to store the obtained session data. It is 

valid only if COBW3-SESSION-DATA-GROUP has been set as the session data 

format during session startup. 

Value Meaning 

1 to 999999999 Gets the specified length of session data. If it differs from the session 

data registered in the session, an error is returned. 

• Session data 

Specifies a data item to store the session data obtained. It can be a group item 

or an object reference item, depending on the session data format. 

Notes: If an object reference item has been registered in the session data, the 

object reference item must be initialized by the NULL object and set in the calling 

parameter of this subroutine. If not initialized by the NULL object, no session data 

can be obtained. When specifying an object reference item in the session data, 

specify the object reference item with the USAGE OBJECT REFERENCE clause and 

specify no other items. 

If the session data obtained differs from the session data format which has been set 

during session startup, the Web application operations are unreliable. 


None

COBW3_ALTER_SESSION_TIMEOUT 


Alters the current session timeout (in seconds). 

Notes: Call this subroutine when the session is established. No session timeout can 

be altered if the subroutine is called before or after the session. 

Format: 

CALL "COBW3_ALTER_SESSION_TIMEOUT" USING COBW3. 



Specifies a session timeout (in seconds). This is the maximum waiting period 

from the time when the “COBW3_FREE” is called to the time when the 

“COBW3_INIT” is called in the next thread of the same session. 

Value Meaning 

1 to 999999 Timeout processing is executed when the specified time (in seconds) has 

passed. 


None 

COBW3_GET_SESSION_INFO 

Gets the current session information. 

Format: 

CALL "COBW3_GET_SESSION_INFO " USING COBW3. 


None 



Gets the timeout (in seconds) for the current session. 

• COBW3-SESSION-ID 

Gets the current session identification (ID) value. 


Gets the data length (in bytes) of the current session. It can be obtained only 

when COBW3-SESSION-DATA-GROUPITEM has been set for the session data 

format during session startup. Zero (0) is set if COBW3-SESSION-DATA-OBJECT 

is set for the session data format. 

• COBW3-SESSION-DATA-TYPE 

Sets a data type of the current session.



COBW3-SESSION-DATA–GROUPITEM “0” A group item is used as the session 

data. 

COBW3-SESSION–DATA-OBJECT “1” An object reference item is used as the 

session data. 

• COBW3-SESSION-STATUS 

Sets the current session status. 


COBW3-SESSION-STATUS-NON “0” The session is not started yet or 

already ended. 

COBW3-SESSION–STATUS-STARTED “1” The session has been started up. 

SAF-Specific Subroutines 

COBW3_SAF_GET_PARM, COBW3_SAF_GET_PARM_XX, 

COBW3_SAF_GET_PARM_NX, COBW3_SAF_GET_PARM_XN, 

COBW3_SAF_GET_PARM_NN 

Search for an NES parameter name in the NES parameter information and get the 

parameter value corresponding to the NES parameter name. 



• COBW3_SAF_GET_PARM 

Searches for an NES parameter name consisting of an alphanumeric character 

string, and returns the corresponding NES parameter value in an alphanumeric 

character string. 


• COBW3_SAF_GET_PARM_XX 


string, and returns the corresponding NES parameter value in an alphanumeric 


• COBW3_SAF_GET_PARM_NX 

Searches for an NES parameter name consisting of a national character string, 

and returns the corresponding NES parameter value in an alphanumeric 


• COBW3_SAF_GET_PARM_XN 


string, and returns the corresponding NES parameter value in a national 

character string.


• COBW3_SAF_GET_PARM_NN 

Searches for an NES parameter name consisting of a national character string, 

and returns the corresponding NES parameter value in a national character 

string. 

Padding characters for storing the obtained NES parameter value are blank. 

Note: As the NES parameter name is case-sensitive, the ALPHAL (WORD) or 

NOALPHAL compiler option must be used if necessary. 

Formats: 

• 

• 

CALL "COBW3_SAF_GET_PARM" USING COBW3SAF. 

CALL "COBW3_SAF_GET_PARM_XX" USING COBW3SAF. 

CALL "COBW3_SAF_GET_PARM_NX" USING COBW3SAF. 

CALL "COBW3_SAF_GET_PARM_XN" USING COBW3SAF. 

CALL "COBW3_SAF_GET_PARM_NN" USING COBW3SAF. 

COBW3 Data for Calls:COBW3-SAF-PARM-NAME, COBW3-SAF-PARM-NAME-N 

Set a NES parameter name to be located. 

Specify the NES parameter name in COBW3-SAF-PARM-NAME for 

COBW3_SAF_GET_PARM, COBW3_SAF_GET_PARM_XX or 

COBW3_SAF_GET_PARM_XN. 

Specify it in COBW3-SAF-PARM-NAME-N for COBW3_SAF_GET_PARM_NX or 

COBW3_SAF_GET_PARM_NN. 

COBW3-SAF-PARM-NAME-LENGTH [Optional] 

Sets a length of NES parameter character string (in bytes) for search of a NES 

parameter name if it ends with a valid space. 

Value Meaning 

0 The NES parameter name of the entire length of character string except for 

spaces. However, if the COBW3-SAF-PARM-NAME or COBW3-SAF-PARM- 

NAME-N is only spaces, the length of character string is considered to be zero. 

1 to 64 The specified length of NES parameter name is searched.



• COBW3-SAF-SEARCH-FLAG 

• 

• 


COBW3-SAF-PARM–FLAG-NON “0” The specified NES name is not found. 

COBW3-SAF-PARM–FLAG-EXIST “1” The specified NES name has been found. 

COBW3-SAF-PARM-VALUE, COBW3-SAF-PARM-VALUE-N 

Set an NES parameter value corresponding to the NES parameter name to be 

located. 

The NES parameter value is set in COBW3-SAF-PARM-VALUE for 

COBW3_SAF_GET_PARM, COBW3_SAF_GET_PARM_XX or 

COBW3_SAF_GET_PARM_NX. 

Set it in COBW3-SAF-PARM-VALUE-N for COBW3_SAF_GET_PARM_XN or 

COBW3_SAF_GET_PARM_NN. 

COBW3-SAF-PARM-LENGTH 

Sets a length of character string of NES parameter value (in bytes) 

corresponding to the NES parameter name to be searched. 

COBW3_SAF_GET_BASENAME 

Gets an application name to be set in the URL. 

Note: As an application is identified by its MIME type (extender) in NES, the 

application name can be used as part of input data for process switching. The 

application name can contain any character. However, the operations are unreliable 

if a character other than “a” to “z,” “A” to “Z,” “0” to “9,” “-“ (hyphen) or “_” 

(underscore) is included. 

Format: 

CALL "COBW3_SAF_GET_BASENAME " USING COBW3SAF. 


None 


• COBW3-SAF-BASENAME 

Gets an application name. 

• 

COBW3-SAF-BASENAME-LENGTH 

Gets the length the application name (in bytes).

Data Length Restrictions of SAF Subroutines 

The data length is limited as follows in SAF subroutines. 


Item Value 

Maximum length of Web parameter (*1) 1073741822bytes 

Maximum length of character string of Web parameter NAME 1024 bytes 

Maximum length of character string of Web parameter VALUE 1024 bytes 

Maximum record length of result output page (file) to be specified 

in COBW3-HTML-FILENAME (*2) 

Length of a single line of result output page after updating of 

conversion data 

1024 bytes 

3072 bytes 

*1 The data format of the Web parameter is different according to the specification 

of ENCTYPE of the FORM tag. The data of the file up-loading etc. besides NAME and 

VALUE are included in the Web parameter. Moreover, when the memory which can 

be used is a little, data might not be able to be received even when the size of data 

does not exceed the fixed quantity limitation because the Web parameter is acquired 

on the memory of the machine with WWW Server. Therefore, you should display the 

size of the file which can be up-loaded to the Web page for the invoking application, 

or display not to up-load the file which exceeds the limitation Web page for invoking 

application if it is necessary. Refer to the book or the homepage, etc. to explain 

HTML for details of the data format of the Web parameter. 

*2 If an HTML document is created by use of a commercial HTML editor, the length 

of a line may exceed 1024 bytes. For use with SAF subroutines, rearrange the HTML 

to reduce the maximum line length to 1024 bytes, using a text editor. 

Classes Provided by SAF Subroutines 

The SAF subroutines provide the following classes for use by session management 

functions. 

COBW3-SESSION-ADAPTER class 

Used to manage an object registered as the session data. The object to be 

registered in the session data must be generated from a class that inherits this class. 

Also, timeout processing must be written in the method which has overwritten the 

SWEEP-SESSION method of this class by use of OVERRIDE clause. 

Note: Timeout processing can be used only when an object reference item is 

registered in the session data. 

No SAF subroutine can be called by timeout processing. 

Factory method: 

None


Object method: 

• SWEEP-SESSION 

This method is called when a session is timed out. It is used to perform 

processing such as file closing and database (DB) commitment/rollback. 

Method argument: 

None 

Method return information: 

None 

Note: 

• If a session is timed out, the SAF subroutine calls the SWEEP-SESSION method 

and assigns a NULL object to the object reference item which has been 

registered in the session data. 

• If the default SWEEP-SESSION method is not replaced by a user-written method, 

nothing is executed by the SWEEP-SESSION method. 

• The COBW3-SESSION-ADAPTER class inherits the FJBASE class. 

Example: 



CLASS-ID. SESSDATA INHERITS COBW3-SESSION-ADAPTER. 

: 


OBJECT. 

: 


METHOD-ID. SWEEP-SESSION OVERRIDE. 


: 


: 

* Write down timeout processing if necessary. 

: 

END METHOD SWEEP-SESSION 

: 

END OBJECT. 

END CLASS SESSDATA.

Chapter 4. Generating and Executing a Web 

Application 

This chapter explains the basic method for compilation, linkage, and execution of 

Web applications using SAF subroutines. 

For details of compile options and link options that are not explained in this chapter, 

refer to the NetCOBOL User's Guide. 

This section gives basic explanations of how to compile, link, and execute the Web 

application. For compile options and link options that are not explained in this 

section, see "NetCOBOL User's Guide."

70 Chapter 4. Generating and Executing a Web Application 

Executing a Web Application 

To execute a Web application, follow the procedure below. 

1. Compile and link the program. 

For details, see "Compiling and Linking". 

2. Set the environment. 

- Set up the environment for the NES. For details, see "NES Setup". 

- Set up the environment for SAF subroutines. For details, see "Environment 

Variable Setup for SAF Subroutines". 

3. Execute the Web application. 

Display the Web page that invokes the application (HTML document) and start 

the application. 

For details, see "Executing a Web application". 

Compiling and Linking 

A program created that uses SAF subroutines is compiled and linked as shown below. 

In the example, the file name is MainProc.cob and the entry-name is SAF-MAIN. If 

the Project Manager is used, use the build utility of the project manager for 

compiling and linking. 

• Compile the COBOL source program. 

Two methods of compiling the COBOL source program are provided: By 

executing the WINCOB command from the Project Manager and by using the 

compile command at the command prompt. This section shows an example 

using the compile command . 

For details of compiling using the WINCOB command and compiling commands, 

see "NetCOBOL User's Guide." 

COBOL32 –WC, "THREAD(MULTI)" MainProc.cob 

Notes: SAF is a multi-thread application, so the compile option THREAD (MULTI) 

must be specified. In order to distinguish upper-case letters/lower-case letters of an 

application entry-name, or NES parameter name accessed by a subroutine such as 

COBW3_SAF_GET_PARM_XX, specify the compile option ALPHAL (WORD) or 

NOALPHAL . 

• Link the COBOL object program. (.DLL generation) 

Two methods of linking the object program are provided: By executing the 

WINLINK command from the Project Manager and by using the link command at 

the command prompt. In this section, an example of linking by using the link 

command is given. For details of linking by using the WINLINK command and 

link commands, see "Net COBOL User's Guide." 

The .DLL generated in this example is SAFSMPL.dll. 

The link operation is as follows:

NES Settings 

Chapter 4. Generating and Executing a Web Application 71 

LINK /DLL /OUT:SAFSMPL.dll MainProc.obj 

F3BICBDM.obj F3BINSRT.lib F3BICIMP.lib KERNEL32.LIB LIBC.LIB 

/ENTRY:COBDMAIN 

The initialization file (COBOL85.CBR) can be allocated in the same folder as the .DLL, 

regardless of the current folder, by linking F3BICBDM. obj and 

specifying/ENTRY:COBDMAIN. It is very useful that the initial file can be allocated in 

the same folder as the .DLL since the current folder of the application under the 

server such as an NES is undefined. For details, see "NetCOBOL User's Guide. 

The following items must be set for NES when executing the Web application. 

• Define the SAF director to NES. 

• Define the Web application to the SAF director. 

• Register the MIME type of the application with NES. 

Defining the SAF Director to NES 

Note: Modification of the obj.conf file is not reflected to NES until NES is restarted. 

Initialize the SAF director in NES by editing obj.conf file in the folder where NES is 

installed. 

Open obj.conf file by using an adequate text editor. Locate lines starting with “Init” 

near the beginning of the file. Add the following description at the end of lines. In 

this example, the folder in which the COBOL is installed is set to C:\COBOL. The SAF 

director is in that folder. 

Init fn= "load-modules" shlib="C:/COBOL/F3BINSAF.dll" 

funcs="COBOL_Init,COBOL_Perform" 

Notes: 

• 

• 

• 

Normally, a setting is written on a single line. When writing it over multiple 

lines, a space or tab must be written at the beginning of each continuation line. 

Do not edit other lines starting with Init . NES may fail to initialize. 

Backup of obj.conf file before editing is recommended. 

Defining the Web Application to the SAF Director 

In order to execute the Web application in NES, define the Web application to the 

SAF director. 

When NES is started, the SAF director loads the Web application and executes the 

loaded Web application in response to each request.


• Load specification of Web application when NES is started 

Add the following description after the SAF director definition in obj.conf file. 

Init fn="COBOL_Init" load=" dll name, entry-name [;dll name, entry-name]…" 

[env="environment setup file"] 

[sev="log output severity of SAF director”] 

In the following example, settings are as follows: 

• 

• 

• 

The folder to which the Web application is allocated is C:\COBAPL. 

The Web application name and entry-name are SAFSMPL1.DLL, SAMPLE 1, and 

SAFSMPL2.DLL, SAMPLE2. 

The environment setup file is C:\COBAPL\SETUP1.BAT and log output severity of 

SAF director logging is set to 1. 

Init fn= "COBOL_Init" 

load="C:/COBAPL/SAFSMPL1.dll,SAMPLE1;C:/COBAPL/SAFSMPL2.dll,SAMPLE2" 

env="C:/COBAPL/SETUP1.BAT" sev="1" 

Note: For descriptions of the environment setup file, see "COBOL_Init". 

• Specifying Web application execution 

Specify the Web application to be started in response to each request. Add the 

following description to an adequate position in lines starting with “Service” in 

obj.conf. 

Service type="MIME type" fn="COBOL_Perform" app="DLL name, entry-name" 

[sev="log output severity of SAF director"] 

Note: Add the description above to the position enclosed with tags and . When using another object tag, see the NES 

manual. Moreover, if two or more Web applications can be started, the description 

above of each application is added. At this time, the MIME type specifies the one 

different in each Web application. 

In the following example, settings are as follows: 

• MIME type is "magnus-internal/cob-app1." 

• The folder to which the Web application is installed is C:\COBAPL. 

• The Web application name and entry-name is C: \COBAPL\SAFSMPL1.DLL, 

SAMPLE 1. 

• The log output severityof the SAF director is set to 1. 

service type="magnus-internal/cob-appl" 

fn="COBOL_Perform" app="C:/COBAPL/SAFSMPL1.DLL,SAMPLE1" 

sev="1" 

Note: A character-string "magnus-internal/" must be registered with the NES as a 

MIME type.

MIME Type Setup 


Register the MIME type using the NES administration page. First open the "Netscape 

Server Administration" page. 

Pressing the Web site button ("cobol-svr" button in the figure above) on this page 

displays the "Server Preference" page. Click "MIME Types" and "Global MIME Types" 

page is displayed.


Set a new MIME type on this page. Specify the MIME type used in Section "Defining 

the Web application to the SAF director." Specify "magnus-internal/cob-app1." Also 

set the File Suffix in order to specify the Web application. Specify "cobap1" here. 

Any character-string may be used as the file suffix as long as it does not duplicate a 

previous suffix. 

The “type” must be specified to a category. 

Pressing "New Type" button after entering the data displays the "Save and Apply 

Changes" page. Then, press the "Save and Apply" or "Save" button to save the 

setup.


Environment Variable Setup for SAF Subroutine 

In order to execute the Web application using the SAF subroutine, it is necessary to 

set the following execution environment information in an environment variable, or in 

the SAF director environment setting, or initialization file (COBOL85. CBR) . When 

using an initialization file , link each application with F3BICBDM.obj so that an 

initialization file in the application folder can be referenced. The use of an 

environment setup file of the SAF director is recommended, since an initialization file 

(COBOL85.CBR) is not validated until the COBOL program is executed for the first 

time. For description of the environment setup file, see "COBOL_Init" in Chapter 4. 

Notes: The NES deletes system environment variables which the NES does not 

require from the environment variable block. Thus, environment variables needed by 

the SAF subroutine and the Web application cannot be accessed even though they 

are set as system environment variables. For this case, use environment setup file of 

the SAF director or initialization file (COBOL85.CBR) for the environment variables 

that are required by the application. For environment variables used by the NES, see 

the NES manual. 

When the environment variable specified that system environment variable, 

environment setup file of the SAF director and initialization file (COBOL85.CBR) 

overlaps, the priority level becomes as follows. 

Initialization file (COBOL85.CBR) > environment setup file of SAF director > system 

environment variable 

The one to be set in System environment variable or environment setup file of the 

SAF director


PATH 

Include the path of the dynamic-link library (.DLL) used by the Web application. 

The one to be set in environment setup file of SAF director or 

initialization file (COBOL85.CBR) 

@CBR_ATTACH_TOOL=TEST [Start parameter] 

Specifies whether to start (TEST) the debugger at the time of application execution. 

If there is a debugger start parameter, it can be specified after "TEST" in this 

variable. 

Please refer to Chapter 5, "Debugging a SAF Application" for more information. 

@MessOutFile = file name 

Specifies the name of the file to which the execution message to be output from the 

COBOL run time system is stored. This specification suppresses the message box 

being output to the screen. Use the absolute path for the file name. If the file 

already exists, messages are added to the end of file . 

@WinCloseMsg = OFF 

Specifies whether to display the confirmation message (ON) or not (OFF) when 

closing the window. When executing the application on the Web application, elect 

not to display the confirmation message (OFF). 

@CBR_SAF_LOGFILE = log file name 

Specifies the SAF log file output by the SAF subroutine. It is useful when debugging 

SAF failures. Use the absolute path for the file name. If the file is not specified, no 

log is output. 

@CBR_SAF_SEVERITY = severity 

Specifies the severity of log information to be output by the SAF subroutine. The 

following values can be specified. If any other value is specified, or when nothing is 

specified, 0 is assumed. 

0 Only fatal error messages are output. 

1 In addition to fatal errors, severe error messages are output. 

2 In addition to severe errors, an warning messages are output. 

3 In addition to warnings, a trace of the SAF subroutine is output. 

Notes: 

As more logging is enabled, the slower the application runs . Specify the value 

needed to log only as much detail as required. We do not recommend specifying 3 

unless all other options are insufficient. 

For other execution environment information , see "NetCOBOL User's Guide."

Executing a Web Application 


Place the MIME extension used by the Web applicationin the ACTION attribute of the 

FORM tag in the Web page that invokes the application as follows: 

 

 

sample 

 

 

: 

 

 

 

Allocate this Web page (HTML document) in an appropriate document directory of 

NES and start the application by using it. 

Note: Web applications may be frequently modified during testing. In operation 

environment, however, NES keeps the first copy of the application that it loads in 

memory, so that NES must be stopped and restarted to load the modified version. It 

is possible to stop and restart the NES from the NES administration screen. 

SAF Director Reference 

COBOL_Init 

Specify the Web application to be loaded by NES and the environment setup file for 


Format: 

Init fn="COBOL_Init" 

[load="DLL name1, entry-name 11 [, entry-name 12]…[;DLL name 2, entry-name 

21 [, entry-name 22]…]…"] 

[env="environment setup file"] [sev="log output severity of SAF director"] 

Parameters: 

• load 

Target DLL names for loading and entry-names scheduled for execution are 

listed. Use an absolute path for the .DLL name. Use commas for delimiting 

entry-names belonging to the .DLL. Specify at least one entry-name for a .DLL. 

To specify multiple .DLL names, use a semi-colon. 

• 

env 

Specify an absolute path for an environment setup file. In the environment 

setup file, specify variables as follows: 

SET environment variable name = environment variable value 

Given below is an example of environment setup file description when the Web 

application is stored in "C:\COBAP."


set PATH=C:\COBAP;%PATH% 

rem **For COBOL setting ** 

set @WinCloseMsg=OFF 

set @MessOutFile=C:\COBAP\LOG\cobol.txt 

rem ** For SAF subroutines settings ** 

set @CBR_SAF_LOGFILE=C:\COBAP\LOG\safap.txt 

set @CBR_SAF_SEVERITY=0 

To write a comment line, write REM at the beginning of the line. 

The difference between uppercase and lowercase letters is not significant in the 

“SET” and “REM” keywords, But they are in environment variable names and 

environment variable values. 

Notes: To write COBOL_Init over multiple lines when specifying an environment 

setup file for env, write the environment setup file only for the first COBOL_Init or 

write the same environment setup file for multiple lines. If environment setup files 

written in multiple COBOL_Init lines are different, results are not guaranteed. 

• sev 

Specify the severity of log information to be output by the SAF director. The 

following values can be specified . If any other value is specified, or if nothing is 

specified, 0 is assumed. 


1 In addition to fatal messages, severe error messages are output. 

2 In addition to severe messages, warning messages are output. 

3 In addition to warning messages, a trace of the SAF subroutine is output. 

The log information that is output by the SAF director is recorded in the same place 

as the error log of NES. To view the SAF director and NES error logs, use the 

administration page of the NES for reference. 

Notes: Each specification of severity by sev is valid in each COBOL_Init. This 

specification has nothing to do with the severity (env) specified in COBOL_Perform 

The severity of log information to be specified here does not have any effect on the 

log information that is output by the SAF subroutine. For the log information that is 

output by the SAF subroutine, see "Environment Variable Setup for SAF Subroutines". 

As more logging is enabled, the slower the SAF Director runs . Specify the value 



Notes: NES deletes environment variables in the system, except what NES requires. 

Thus, use the environment setup file for the environment variables that are required 

by the application. 

COBOL_Perform 

Execute the Web application. If the Web application has been loaded by 

COBOL_Init, the application is executed. If it has not been loaded, it is loaded at this 

time. After the application is loaded, it stays in NES while being loaded.

Format: 


Service [type="MIME type"] fn="COBOL_Perform" app="DLL name, 

entry-name" 

[sev="log output severity of SAF director"] 

Parameters: 

• 

• 

app 

Specify the .DLL name and an entry-name of the COBOL application to be 

executed. Specify an absolute path as a DLL name in the same way as in 

COBOL_Init. 

sev 

Specify the severity of log information to be output by the SAF director. The 

following values can be specified. If any value besides those is specified, or 

when nothing is specified, it is regarded as 0 specified. 


1 In addition to fatal messages, severe error messages are output. 

2 In addition to severe messages, warning messages are output. 

3 In addition to warning messages, a trace of the SAF Director is output. 

The log information that is output by the SAF director is recorded in the same place 

as the error log of NES. To view the SAF director and NES error logs, use the 

administration page of the NES for reference. 

Notes: Each specification of severity by sev is valid in each COBOL_Perform. This 

specification has nothing to do with the severity (env) specified in COBOL_Init. 

The severity of log information to be specified here does not have any effect on the 

log information that is output by SAF subroutine. For the log information that is 

output by the SAF subroutine, see "Environment Variable Setup for SAF Subroutines". 

As more logging is enabled, the slower the SAF Director runs . Specify the value 



Note: For other parameters that can be specified on “Service” lines, see the NES 

manual.

80 Chapter 4. Generating and Executing a Web Application

Chapter 5. Debugging a SAF Application 

The following resources are provided for checking the execution of a SAF application 

during testing or when an error occurs. 

• Log information 

• The Interactive Debugger 

• Displaying errors detected by SAF subroutines on the Web page 

• Displaying Working-Storage data or messages on the Web page 

The following sections explain the use of each method.

82 Chapter 5. Debugging a SAF Application 

Referring to the Log Information 

SAF subroutines contain a logging feature that may be turned on or off by an 

environment variable. For setting this feature, see "Environment variable setup for 

SAF subroutine" in Chapter 4. Since it is the log information of SAF subroutines, it is 

not a program trace, but it provides a record of the SAF subroutine calls made by the 

program. The log file record format is as follows: 

Process ID thread ID year-month-day hour:minute:second severity message 

A concrete example of the configuration is given below. 

0000000188 0000000187 1999-02-02 11:48:07 02 COB-06310: COBW3: The specified 

conversion name has already been set. The conversion information that has already 

been set is validated. 

0000000188 0000000181 1999-02-02 11:48:10 01 COB-04470: COBW3: The conversion 

information specified could not be changed because it has not been set. 

To collect trace information from an application, itself, use the TRACE function of 

COBOL. For details of the TRACE function, see "NetCOBOL Debugging Guide." 

For details of the log output by SAF Director, see " SAF Director Reference" in 

Chapter 4. 

Checking Execution Using the Interactive Debugger 

The debug the Web application generated in the COBOL, by using the debugger, use 

the method of starting the debugger from the program to be debugged. 

The Web application can be remotely debugged from the client which starts a WWW 

browser by using a remote debugger. Please refer to “NetCOBOL Debugging Guide” 

for the usage of a remote debugger. 

The following must be noted when debugging an application by using the interactive 

debugger because NES reads all Web applications into the same memory space. 

• 

• 

If a Web application operates incorrectly, not only the application being 

debugged but also other Web applications loaded at the same time and NES 

itself may fail. We recommend using the interactive debugger only when other 

Web applications are not in use. If this is successful, then you can check 

operations when other Web applications are active. 

The debugger debugs not only the Web application being tested, but also other 

Web applications and NES itself. If the debugger terminates, other Web 

applications and NES will also terminate and it will be necessary to restart NES.

Starting the Debugger 

To start debugging, follow the procedure below: 

Chapter 5. Debugging a SAF Application 83 

1. Compile and link the Web application. 

Specify the compile option and the link option for debugging and generate the 

Web application. For methods of compiling and linking for debugging, see 

"NetCOBOL Debugging Guide." 

2. Set the run-time environment variables. 

Before starting the debugger from a program to be debugged, you need to set 

the following run-time environment information. For information on setting the 

run-time environment information, see "Environment variable setup for SAF 

subroutine" in Chapter 4. 

@CBR_ATTACH_TOOL = TEST [start parameter] 

Specify whether to start (TEST) the debugger at the time of application 

execution. It is possible to specify the debugger start parameter, if any, after 

specifying "TEST." For an explanation of the start parameter, see "NetCOBOL 

Debugging Guide." 

3. Log on to the computer on which the Web application to be debugged is to be 

executed. 

4. Start the web application from a WWW browser. The WWW browser need not 

run on the computer on which the Web application is to be executed. 

5. When the Web application is started, the debugger is automatically started. 

When the debugger is started, specify the debugging information file storage 

folder and necessary information, and then start debugging. 

Debugging 

You can debug a Web application just like any regular COBOL application using the 

debugger. For instructions on using the debugger, see "NetCOBOL Debugging 

Guide." Before starting debugging, however, note the following: 

• 

• 

• 

The debugger automatically interrupts the execution at the entry to the Web 

application to allow setting breakpoints or other options. Subsequent calls to the 

application are not interrupted unless at least one breakpoint is set. To interrupt 

the execution of a Web application loaded by the next request, specify the name 

of the program to be loaded at a command or in a dialog box to specify a 

breakpoint. For details, see "Debug functions for dynamic structured programs" 

in "NetCOBOL Debugging Guide." 

After responding to the WWW browser, the program remains running in a wait 

state for the next request. To perform a debugging operation such as setting a 

breakpoint, select the “Break“ command from the debugger menu to interrupt 

program execution for debugging. 

When debugging, note also the followings. 

When using the debugger, the application takes longer time than the normal 

time for operation. Thus, a timeout may occur during debugging depending on 

the WWW browser. If it is possible to specify a timeout in the browser, change 

the value to an adequate value. Also change the timeout value in NES to an 

adequate value.

84 Chapter 5. Debugging a SAF Application 

• 

• 

• 

• 

Normally, when NES is fails, it is automatically restarted. When using the 

debugger, change NES setup if it is unnecessary that NES restart automatically. 

Terminating the Debugger 

When terminating the debugger first 

When the debugger terminates, NES also terminates. Thus, it is necessary to 

restart NES. 

When terminating the Web application first 

Stop NES. To stop NES, use the WWW browser "Netscape Server 

Administration" page. When you stop NES, the Web application must be running 

until the process is terminated. 

Switch the Web application as follows: 

Stop NES and switch the Web application, then restart NES. 

To stop and start NES, use the WWW browser from “Netscape Server 

Administration” page. When you stop NES, the Web application must be running 

until the process is terminated. 

Displaying Errors Detected by SAF Subroutines 

To display errors detected by SAF subroutines, set the debug mode just before 

calling COBW3_INIT in the program. 

SET COBW3-DMODE-DBG TO TRUE. 


If an error is detected in a SAF subroutine , an error message is displayed in the 

WWW browser. 

If the setting for header output is not COBW3-CONTENT-TYPE-NON, it is regarded as 

COBW3-CONTENT-TYPE-HTML and COBW3_INIT declares the content-type. 

Supplements 

To set the debug mode, it is necessary to modify the program and regenerate the 

Web application. Setting the debug mode enables referring to an error message to 

be displayed on the WWW browser even in the log information. So, we recommend 

using the log information if you want to refer to an error message without changing 


Notes: The COBW3-DMODE-DBG setting can not be used in a Unicode 

environment. Check the operation by means such as referring to the log information.

Chapter 5. Debugging a SAF Application 85 

Displaying Working-Storage Data or Messages in a Web Page 

To display your own messages or data on the browser screen, use 

COBW3_PUT_TEXT. 

Notes: COBW3_PUT_TEXT can display only character data. Moreover since repeat 

operations of compiling and executing frequently occur, the operation becomes less 

efficient. Therefore, in such a case, we recommend debugging by using the method 

of referring to the data in progress of execution by an interactive debugger.

86 Chapter 5. Debugging a SAF Application

Chapter 6. Samples 

This chapter explains the sample programs. 

Each example uses SAF subroutines to pass data between Cookie applications and to 

exchange information with the server and the browser.

88 Chapter 6. Samples 

Program Files Provided 

• 

• 

• 

• 

• 

• 

Subroutines Used 

SAFMAIN.cob (COBOL source program) 

SAFSTART.htm (Web page for invoking application) 

SAFRPLY1.htm (Web page for processing output) 

SAFRPLY2.htm (Web page for processing output) 

SAFERROR.htm (Web page for processing error output ) 

COBOL85.cbr (Initialization file for program execution) 

The following SAF subroutines are used in the examples. 

• COBW3_INIT 

• COBW3_SET_CNV 

• COBW3_PUT_HTML 

• COBW3_RECEIVE_HEADER 

• COBW3_GET_REQUEST_INFO 

• COBW3_SET_COOKIE 

• COBW3_GET_COOKIE 

• COBW3_FREE 

Program Compiling 

The following shows how to compile a program using COBOL32 commands. If you 

have already copied the library file (COBW3.cbl) used by SAF subroutines to the 

sample folder, you can omit the “-I” option. The COBOL installation folder is 

“C:\COBOL” in the following examples. 

Program Linkage 

COBOL32 – IC:\COBOL –WC, "THREAD(MULTI)" SAFMAIN.cob 

Link and create a .DLL as follows. 

link /dll /out:SAFSMPL1.dll SAFMAIN.obj 

C:\COBOL\F3BICBDM.obj F3BINSRT.lib F3BICIMP.lib 

kernel32.lib libc.lib/ENTRY:COBDMAIN

Environment Setup 

Chapter 6. Samples 89 

Modify the “COBOL85.cbr” initialization file depending on your operating 

environment. Set up NES for execution of Web applications. For NES setup details, 

see “NES setup” in Chapter 4. 

Register the MIME extension used in the ACTION attribute of the FORM tag of the 

calling page in NES or modify the calling page according to the extension you have 

registered in NES. 

Sample Execution 

Make sure that the NESis started and display the Web page for invoking the 

application (SAFSTART.htm) in the WWW browser. Then, follow the on-screen 

instructions and press the “Execute” button. 

Supplements: 

If you wish to convert sample operation codes into Unicode, add the “RCS (UCS2)” 

compile option during program compiling and convert all HTML documents into 

Unicode. 

Note: This sample does not operate correctly if you have set the WWW browser not 

to accept Cookies. 

Explanation of Samples 

The following paragraphs show the Web page for invoking the application 

(SAFSART.htm), Web pages for processing output (SAFRPLY1.htm, SAFRPLY2.htm) 

and the COBOL program (SAFMAIN.cob) . 

Web page for invoking the application (SAFSTART.htm) 

 

 

Start screen 

 

 

This is a sample which is used SAF subroutine. 

If you confirm the operation, please press “Execute” button. 

If you exit, please close this browser. 

 

 

 

 


First Web page for processing output (SAFRPLY1.htm) 

 

 

First Access Screen 

 

 

Thank you very much for having the first time 

 

If you use continuously, please press “Execute” button. 

If you exit, please close this browser. 

 

 

 

 

 

Second Web page for processing result output (SAFRPLY2.htm) 

 

 

Screen since first time 

 

 

Current situation is as follows. 

 

 

Hostname for accessed host 

Browser name 

Access count 

 

 

COBOL program (SAFMAIN.cob) 


000010*---------------------------------------------------------* 

000020* All Rights Reserved, Copyright© FUJITSU LIMITED 2000-2002 * 

000030* * 

000040* Filename: SAFMAIN.cob * 

000050* Abstract: Example demonstrating the SAF subroutine * 

000060*---------------------------------------------------------* 

000070 identification division. 

000080 program-id. SAF-MAIN. 

000090 environment division. 

000100 data division. 

000110 working-storage section. 

000120 copy COBW3. 

000130* 

000140 01 HTMLFilename pic X(64). 

000150 01 pathName pic X(256). 

000160 01 pathSize pic 9(05). 

000170 01 copyStartPos pic 9(05). 

000171 01 leftLength pic 9(05). 

000180 01 AccessCount pic 9(05). 

000190* 

000200 linkage section. 

000210 01 safCtx pointer 

000220* 

000230 procedure division using safCtx. 

000240* 

000250 SafSample1-Start. 

000260* 

000270* Initialize the work area for the SAF subroutine 

000280 move low-value to COBW3. 

000290 set COBW3-CONTEXT to safCtx. 

000300* 

000310* Initialize the SAF subroutine work environment and obtain 

000320* a Web parameter. 

000330 call "COBW3_INIT" using COBW3. 

000340* 

000350 move space to pathName. 

000360* 

000370 move "Your Access Counter" to COBW3-COOKIE-NAME. 

000380 call "COBW3_GET_COOKIE" using COBW3. 

000390 if program-status not = zero then 

000400 move "SAFERROR.htm" to HTMLFilename 

000410 performoutputScreenProc 

000420 else if COBW3-SEARCH-FLAG-NON then 

000430 move 1 to COBW3-COOKIE-VALUE 

000440 perform entryAccessCounterProc 

000450 move "SAFRPLY1.htm" to HTMLFilename 

000460 perform outputscreenProc 

000470 else 

000480 perform outputContinuousScreenProc. 

000490 end-if. 

000500* 

000510 Finish-Pos. 

000520* 

000530* Release the resource obtained by the SAF subroutine 

000540 call "COBW3_FREE” using COBW3. 

000550* 

000560 SafSample1-End. 

000570* 

000580 exit program. 

000590* 

000600 outputContinuousScreenProc section. 

000610* Registration of various conversion data 

000620* Get the Cookie data for AccessCounter 

000630 compute AccessCounter = function NUMVAL(COBW3-COOKIE-VALUE). 

000640 add 1 to AccessCounter. 

000650 move AccessCounter to COBW3-COOKIE-VALUE. 

000660 move zero to COBW3-COOKIE-VALUE-LENGTH. 

000670*


000680* The access counter value is registered in conversion data. 

000690 perform entryAccessCounterProc. 

000700 move “Access Count” to COBW3-CNV-NAME. 

000710 move AccessCounter to COBW3-CNV-VALUE. 

000720 perform entryConversionDataProc. 

000730* 

000740* Get and register remote hostname. 

000750 set COBW3-REMOTE-HOST to true. 

000760 call "COBW3_GET_REQUEST_INFO" using COBW3. 



000790 perform outputScreenProc 

000800 go to Finish-Pos 

000810 end-if. 

000820 move “Hostname” to COBW3-CNV-NAME. 

000830 move COBW3-REQUEST-INFO to COBW3-CNV-VALUE. 


000850* 

000860* Get and register the browser name. 

000870 move "User-Agent" to COBW3-HEADER-NAME. 

000880 call "COBW3_RECEIVE_HEADER" using COBW3. 


000900 move SAFERROR.htm" to HTMLFilename 

000910 perform outputscreenProc 


000930 end-if. 

000940 move “Browser Name” to COBW3-CNV-NAME. 

000950 move COBW3-HEADER-VALUE to COBW3-CNV-VALUE. 


000970* 

000980* Output the prototype HTML file. 

000990 move "SAFRPLY2.htm" to HTMLFilename. 

001000 perform outputscreenProc. 

001010* 

001020 outputContinuousScreenProc-End. 

001030 exit 

001040* 

001050* 

001060 entryAccessCounterProc section. 

001070* After the browser exists the content of the access counter can be 

retained by setting 

001080* an expiration. However, if the browser is different, it is not 

significant. 

001090 call "COBW3_SET_COOKIE" using COBW3. 





001140 end-if. 

001150 entryAccessCounterProc-End. 

001160 exit. 

001170* 

001180 entryConversionDataProc section. 

001190 call "COBW3_SET_CNV" using COBW3. 


001210 move 'SAFERROR.htm" to HTMLFilename 



001240 end-if. 

001250 entryConversionDataProc-End. 

001260 exit. 

001270* 

001280 outputScreenProc section. 

001290* Get the physical path of the application and 

001300* edit the HTML document name. 

001310 if pathName = space then 

001320 perform getPhysicalPath 

001330 end-if. 

001340 move space to COBW3-HTML-FILENAME. 

001350 move pathName(1:pathSize) to COBW3-HTML-FILENAME.


001360 compute copyStartPos = pathSize + 1. 

001370 move "\" to COBW3-HTML-FILENAME(copyStartPos:1). 

001380 compute copyStartPos = copyStartPos +1. 

001390 compute leftLength = 256 – copyStartPos. 

001400 move HTMLFilename to COBW3-HTML-FILENAME(copyStartPos:256). 

001410* 

001420* Output HTML document. 

001430 call "COBW3_PUT_HTML" using COBW3. 

001440* 

001450 outputScreenProc-End. 

001460 exit. 

001470* 

001480 getPhysicalPath section. 

001490 move space to pathName. 

001500 set COBW3-PHYSICALPATH to true. 

001510 call "COBW3_GET_REQUEST_INFO" using COBW3. 

001520 if COBW3-STATUS = zero then 

001530 move COBW3-REQUEST-INFO to pahtName 

001540 move COBW3-REQUEST-INFO-LENGTH to pahtSize 

001550 end-if. 

001560* 

001570 getPhysicalPath-End. 

001580 exit. 

This sample program performs the following 

processing. 

• Get the Cookie data sent from the WWW browser. 

• Register the Cookie data. 

• Output the Web page for processing result. 

Select the output Web page 

according to the Cookie data contents. Register the 

conversion data and edit the output Web page 

if necessary. 

The following diagram shows the progress of the transaction: 

WWW Browser 

SAFSTART.htm 

WWW Browser 

SAFRPLY1.htm 

WWW Browser 

SAFRPLY2.htm 

Only the first 

time 

SAFSMPL1.dll 

Repeats after 

the first time 

The following outlines the purpose and application of each function.


Getting Cookie Data 

Thi s sample uses a Cookie name of “Your access counter.” To get the Cookie data, 

enter this Cookie name in the COBW3-COOKIE-NAME and call 

“COBW3_GET_COOKIE” (lines 370 to 380). 

This sample uses the Cookie data to detect the first access (from “SAFSTART.htm”) 

and to hold the access count data. There is no Cookie data in the first access. 

Therefore, the Cookie data is not found when COBW3_GET_COOKIE is called. In 

such case, initial processing is executed (lines 4 20 to 460). 

In the second or subsequent access, the Cookie data is always sent (lines 470 to 

480). The counter is set to one (1) during initial processing, and it is incremented by 

1 during subsequent processing. 

Registering Cookie Data 

Set the desired Cookie name in the COBW3-COOKIE-NAME, and set its contents in 

the COBW3-COOKIE-VALUE. Then, call COBW3_SET_COOKIE. The registered 

Cookie data is sent to the WWW browser during HTML file output.

Getting Request Information 


To get the request information, set the condition name of the desired information 

and call COBW3_GET_REQUEST_INFO. After getting the request information, the 

information will be in COBW3-REQUEST-INFO. 

This sample gets two sets of request information. One is the physical path 

information of the virtual path. It is used to determine the path name of output Web 

page which is stored in the same path as the application (SAFSMPL1.dll). (See lines 

1490 to 1550.) 

As the current directory is insufficient for applications locating under NES control, the 

path name must be determined based on this information. Otherwise, the absolute 

path must be specified. The second information request gets the host name where 

the WWW browser is running (lines 750 to 810). It is displayed on the screen. 

Getting Header Information 

To get the header information, set the desired HTTP header name in COBW3- 

HEADER-NAME and call COBW3_RECEIVE_HEADER. After getting the http header 

information, the header information will be in the COBW3-HEADER-VALUE. 

This sample uses the header to get the WWW browser information to be displayed 

on the screen. The WWW browser information can be obtained from the “User- 

Agent” header (lines 870 to 930).

96 Chapter 6. Samples

Appendix A. Frequently Asked Questions 

The following are answers to typical questions about the use of SAF subroutines. 

Q1. 

Why is an error message displayed by the WWW browser? 

A1. 

Check the following points. 

• 

• 

The MIME type you have set for WWW server setup and for Web application 

startup by “obj.conf” must match the MIME type that corresponds to the 

extension written in the FORM tag (ACTION) of HTML document. 

The WWW server setup, the program name, and the HTML document storage 

location must be correct. Also, the compiler options must be correct. 

Q2. 

Is it necessary to protect data from external access? 

A2. 

Data may be read or modified by an unauthorized person during communication 

between client and server. We recommend to use appropriate security such as 

Secure Socket Layer (SSL) to protect data from unauthorized access. Consult to the 

server manager or administrator. 

Q3. 

File I/O of a Web application is incorrect. 

A3. 

Each user must be authorized to read/write files when executing a Web application 

that does file I/O. 

Q4. 

How can I change the display dynamically in a Web application? 

A4. 

1. Use the COBW3_SET_CNV_XX or others. 

Write the “//COBOL//conversion-name//COBOL//” in the variable section of the 

Web page for processing result output. Register a character string (a conversion 

character string) to be converted by the conversion name using the 

COBW3_SET_CNV_XX or others, and convert it into the conversion character 

string by the COBW3_PUT_HTML. This can change the page dynamically. 

2. Use the COBW3_PUT_TEXT. 

Usually, data stored in an output file such as HTML document can be written by 

COBW3_PUT_TEXT.

98 Appendix A. Frequently Asked Questions 

Prepare the data of COBW3_PUT_TEXT for each of program conditions, and 

specify the desired data name in the COBW3_PUT_TEXT. This can change the 

page dynamically. 

3. Divide a single page into two or more files. 

An output file can be divided into two or more files. 

Prepare several files which write the second half of the page in the desired 

format. Call COBW3_PUT_HTML, specifying a file name that identifies the first 

half of output page. Then change the output file name according to the program 

conditions, and call the COBW3_PUT_HTML again. 

You can also change the second half of the page dynamically eliminating the 

preparation of multiple similar files. Also, you can create pages to satisfy various 

situations by combination of solutions (1) to (3). 

Q5. 

Why does the Web application not operate after its startup? 

A5. 

Make sure that you have specified “COBW3_INIT” at the beginning of the Web 

application. 

If OK, collect the error information or debug the program by referring to Chapter 5 

“Debugging a SAF Application.” 

Q6. 

Why does the following message appear? 

“Server Error 

The server encountered an internal error or mis-configuration and was unable to 

complete your request.” 

The specified Web application returns only a part of Web header. 

A6. 

The “Content-type” may be incorrect. Review the COBW3-CONTENT-TYPE value you 

have specified in the COBW3_PUT_HEAD. 

1. To output an HTML document: 

Do not call COBW3_PUT_HEAD, omit the COBW3-CONTENT-TYPE value (LOW- 

VALUE), or call COBW3_PUT_HEAD by specifying COBW3-CONTENT-TYPE-HTML. 

2. To output text data: 

Call COBW3_PUT_HEAD by specifying COBW3-CONTENT-TYPE-TEXT.

Appendix A. Frequently Asked Questions 99 

Q7. 

Why does the WWW browser display the “Content-type” declaration? 

A7. 

If the COBW3-DMODE-DBG is specified in COBW3_INIT, the “Content-type” and 

other header information is displayed by the WWW browser as debug information. 

It is not displayed if COBW3-DMODE is not specified. 

Q8. 

Why does the message of the file download appear when I execute the Web 

application? 

A8. 

This type of message may be output if the “Content-type” declaration is incorrect in 

the Web application. Check the “Content-type” declaration for an error. 

Q9. 

Do you have any caution when writing a COBOL program during creation of Web 

application? 

A9. 

You can use almost all COBOL functions directly in a Web application. However, you 

cannot use the following screen operation functions. 

• 

• 

• 

Presentation file module (screen handling module) 

Screen handling module. 

ACCEPT/DISPLAY function (However, you can use the environment variables and 

date and time control functions.) 

For details of Web parameter reception, reference, and process result output, see 

Chapter 3 “How To Use SAF Subroutines.” 

Q10. 

How can I set up environment variables required for WWW server startup? 

A10. 

Add the required environment variables to the environment setup file, and specify 

the environment setup file name in the “env” parameter of the line where 

“COBOL_Init” is set in the “obj.conf” file. Then, restart the NES. 

Otherwise, store the initialization file for execution (COBOL85.CBR) which defines the 

required environment information in the same folder as the Web application (.dll).


Q11. 

Is it impossible to use a COBOL debugger? 

A11. 

You can use a COBOL debugger in the Web environment. See”Checking Execution 

Using the Interactive Debugger” in Chapter5. 

Q12. 

The “Status-code” is displayed by the WWW browser. What does it mean? 

A12. 

Refer to Appendix A of “Web Linkage Guide.” 

Q13. 

Can I control the timeout period while the Web application returns the browser the 

processing result? 

A13. 

This is a WWW server function. Refer to the “WWW server manuals”. 

Q14. 

Can I use an HTML document having frames in a Web application? 

A14. 

You need not specify special setup or processing of frame functions in the Web 

application. You can use the frames in an HTML document if the WWW browser 

supports frame functions. 

Q15. 

Why is the VALUE not searched correctly if the tag is set in the 

COBW3_CHECK_VALUE, etc? 

A15. 

If the NAME is omitted in the INPUT tag, the WWW browser may not enter the 

INPUT tag VALUE in the Web data area. Always specify the NAME in the INPUT tag 

if the VALUE is required. 

Q16. 

Why is a Web parameter not searched correctly if COBW3_GET_VALUE or 

COBW3_CHECK_VALUE is set? 

A16. 

If the length of search character string exceeds the limit in the Web parameter, it is 

truncated by the SAF subroutine. Therefore, you may not have the expected result.


Q17. 

Why does access to a file fail when I specify its absolute path? 

A17. 

Specify the COBOL file storage location according to the drive configuration of the 

server machine you use when you use the file during execution of Web application. 

Q18. 

Why is error message “The document has no data at all” displayed by the WWW 

browser? 

A18. 

Always insert a linefeed before the tag of a Web page that is output by the 

SAF COBOL Web application. 

Example: 

↓ 

↓ 

... 

↓ 

↓ 

↓ 

... 

↓ 

↓ 

Q19. 

The COBOL debugger has started but no debugging starts. 

A19. 

Make sure that [Debugging information file storage folders] has been set correctly in 

the [Debugging Information] page of [Start Debugging] dialog. 

Q20. 

Why is an incorrect value collected by the SAF subroutine? 

A20. 

If the extension path is set in the request URL, the following invalid values may be 

collected. 

• COBW3-URL: URL of request 

• COBW3-URI: URI of request 

• COBW3-MIMETYPE: MIME type of request 

• COBW3-VIRTUALPATH: Virtual path of request 

• COBW3-PHYSICALPATH: Physical path corresponding to the request virtual path 

• A value collected by COBW3_SAF_GET_BASENAME


Q21. 

Why does error message “No F3BIPRCT.DLL is found” appear on the server? 

A21. 

Make sure that the COBOL run-time system has been installed correctly. The USER 

environment variables you have set are invalid for the operation of Web applications. 

First, place the name of the COBOL run-time system install folder in the PATH 

environment variable of the server machine. You must restart the system to validate 

the system environment variables. 

Q22. 

Why does the access to network environment resources fail? 

A22. 

The network drive configuration may not be valid for the Web application when you 

log in. 

Specify the UNC during access to the resources of network environment that you use 

during application execution. For details, refer to “Fujitsu COBOL User’s Guide” in 

Chapter 21. 

Q23. 

What can I do if the server does not respond? 

A23. 

The server may be waiting for an input in a window or a message box. 

When executing a COBOL program on the Web server, write the following 

environment variable information in the initialization file for execution or set the 

information in the system environment variables. 

If you have specified the environment variable information, the windows and 

message boxes are not displayed and you can avoid an operator input wait status. 

Environment variable information Meaning 

@MessOutFile=file-name When the COBOL program is executed, its 

messages are output to the specified file. 

@WinCloseMsg=OFF The window closing message is not displayed. 

For details of the environment variable information, refer to the “Fujitsu COBOL 

User’s Guide.” 

Also, do not use the following window display functions from the COBOL program. 

• Presentation file module (Screen handling module) 

• Screen handling module 

• ACCEPT/DISPLAY function (However, you can use the environment variables and 

date and time control functions.) 

For more information, refer to Subsection 23.1.3 of “Fujitsu COBOL User’s Guide.”


In addition, you may have incorrect NES and ODBS setup (if you are using the 

ODBC). Check them for an error. 

Q24. 

Why does COBOL debugger not start? 

A24. 

Check the following points: 

• The @CBR_ATTACH_TOOL=TEST environment variable information must be set. 

• The COBOL Tool Attaching Service must have started. 

Q25. 

Is it better to back up the “obj.conf” file before changing it? 

A25. 

We recommend to have a backup of “obj.conf” file as you may fail to restart your 

NES after your modification. 

Q26. 

If the Web application that uses session management functions is started twice, it 

may not operate correctly. 

A26. 

The operation of such Web application is unstable if started twice. To avoid this 

problem, use Java script on the WWW browser to prevent duplicate application 

startup. For general notes on WWW browser operations, refer to Appendix A of 

“Web Link Guide.”

104 Appendix A. Frequently Asked Questions

Appendix B. Error Recovery Processing 

If an error is detected while a SAF subroutine is being executed, the SAF subroutine 

executes error recovery processing. 

An error message is output in the following format: 

COB message No.: COBW3: Message text 

• COB message No.: The serial number of the message is displayed. 

• Message text: The error detail is displayed. 

The displayed error content is also output to the log file if logging of SAF subroutines 

is enabled. 

The message numbers and message texts displayed are shown below. 

Message Message text 

number 

00100 The Processing was not able to be continued. Because, the value was not set 

in COBW3-CONTEXT. 

01100 It is thought that the work area or the object was destroyed. Check the 

object of the Web subroutine and the usage of the area. 

01500 The Web subroutine cannot operate correctly in the calling COBOL application 

operation code system. 

01501 The operation state of the calling application is abnormal. The Web 

subroutine cannot operate normally. 

02050 Search character string length specified as a negative value. The processing 

continues as if 0 was specified. 

02051 A value was specified that exceeds the limit for the character string length of 

the search string. The processing continues assuming that the maximum 

length was specified. 

03000 Web application was called by a method without GET or POST. 

03001 COBW3_INIT was called two times or more. Please call COBW3_FREE a 

second time before the call. 

03002 The work area of the Web subroutine could not be acquired. 

03020 The data that was passed by POST or GET was not acquired successfully. 

03030 Failed in the acquisition of the work area of the Web subroutine. 

03040 Uploaded file information could not be acquired. 

03041 The Web parameter can't be processed because failed to acquire header 

information. 

03042 multipart/form-data is specified for ENCTYPE of the FORM tag though the 

method is things except POST. The Web parameter and uploaded file 

information could not be acquired. 

03045 An error in processing the output to the browser. 

03065 Environment variable @CBR_WEB_OUT_CODE was set incorrectly. It is 

assumed that the conversion code was not set 

03200 Conversion from UTF-8 to UCS-2 failed.

106 Appendix B. Error Recovery Processing 

03201 Conversion from UCS-2 to UTF-8 failed. 

03700 A code was specified that could not be recognized as a character. Processing 

continues. 

03701 EUC and SJIS character strings are intermingled. Processing continues. 

03850 Cookie was not acquired successfully. 

04000 There is no Web parameter. 

04001 The Web parameter length is 0. 

04006 A negative value or “0” was specified for COBW3-NUMBER. The processing 

continues as if 1 was specified. 

04008 The length of VALUE data exceeds the limit. The string is truncated to the 

supported length. 

04009 The data passed with POST or GET method was nothing. 

04400 The conversion name is not specified. Please set the conversion name. 

04401 A negative value was specified for character string length of the conversion 

name. The processing continues as if 0 was specified. 

04402 A value was specified that exceeds the limit for character string length of the 

conversion name. The processing continues assuming the maximum length 

was specified. 

04450 Failed to delete the variable name specified in COBW3-CNV-NAME because it 

could not be found in the registered information. 

04470 Failed to change the variable name specified in COBW3-CNV-NAME because it 

could not be found in the registered information. 

04480 Failed to delete the variable name specified in COBW3-CNV-NAME. 

05000 Failed in the execution of the system command. 

05001 The system command is not specified. 

05500 The file name is not specified. Please set the file name. 

05501 There is no uploaded file information. 

05510 Failed to acquire the path name in the client of the uploaded file. 

05511 The character string length of the path name in the client of the uploaded file 

exceeded the limitation. The string is truncated to the supported length. 

05520 Failed to acquire the file name in the client of the uploaded file. 

05521 The character string length of the file name in the client of the uploaded file 

exceeded the limitation. The string is truncated to the supported length. 

05530 Failed to acquire the content type of the uploaded file. 

05531 The character string length of the content type of the uploaded file exceeded 

the limitation. The string is truncated to the supported length. 

05550 The file was not generated because the specified file name had already 

existed. 

05551 Failed to generate the file. 

05552 Failed to generate data in the subroutine. The generated file can't be deleted 

with COBW3_DEL_UPLOADEDFILE. 

05580 The specified file name is not a file generated in the same thread. The file was 

not deleted. 

05581 Failed to delete the specified file. 

06100 An I-O error occurred in the OPEN process of the specified HTML document 

file.

Appendix B. Error Recovery Processing 107 

06101 An I-O error occurred in the READ process of the specified HTML document 

file. 

06102 The length of the specified HTML document file is 0. 

06105 A conversion name in the HTML document was not registered using 

COBW3_CNV_SET. Please register the conversion data using 

COBW3_CNV_SET. 

06106 Failed in the output because the output work area of the HTML document was 

insufficient. Please confirm the conversion data length corresponding to the 

conversion name. 

06107 Failed in the output because an error was found in the specified form of the 

conversion name within the HTML document. 

06108 The string length of the specified conversion name is too long. Check the 

conversion name. 

06120 Failed to output the HTML document to the WWW server. 

06130 The number of characters in one line of the HTML document exceeds the limit. 

The string is truncated to the supported length. 

06300 The conversion name is not specified. Please set the conversion name. 


name. The processing is continued regarding for 0 to have been specified. 


conversion name. The processing continues assuming the maximum length 

was specified. 

06303 The conversion character string is not specified. Please confirm the 

conversion character string. 


character string. The processing continues assuming 0 was specified. 


conversion character string. The processing continues assuming the maximum 

length was specified. 

06310 The specified variable name has already been registered. The old conversion 

information remains effective. 

06320 Failed in registration because the registration work area for the conversion 

information was insufficient. Please register again after calling 

COBW3_CNV_INIT and initializing conversion information. 

06330 Failed to delete conversion information. 

06502 Unexpected error occurred in writing data on standard output. 

06503 A negative value was specified for the length of the string to be output. The 

processing continues assuming 0 was specified. 

06504 A value was specified that exceeds the limit for output character string length. 

The processing continues assuming the maximum length was specified. 

06700 COBW3_PUT_HTML or COBW3_PUT_TEXT has already been called. The 

output request for the header is invalid. 

06702 COBW3-PUT-HEAD contains no colon (:). The specified COBW3-PUT-HEAD is 

ignored. 

06704 A negative value was specified for COBW3-PUT-HEAD-LENGTH. The 


06706 A value was specified that exceeded the limit for COBW3-PUT-HEAD-LENGTH. 

The processing continues assuming the maximum length was specified. 

06708 The object output as a header was not specified.


06710 A value that had already been output and a different value were specified for 

COBW3-CONTENT-TYPE. 

06714 A value that had already been output and a different value were specified for 

COBW3-STATUS-CODE. 

06730 An error not anticipated in the declaration of Content-type occurred. 

06734 An error not anticipated in the declaration of Status-code occurred. 

06736 Unexpected error occurred in declaration of specified header. 

06742 Failed in the output of the specified header. 

06746 The output of the header could not be completed. 

07010 The user name was not able to be acquired. 

07011 The character string length of the user name exceededthe limitation. The 

maximum length is made effective. 

07020 The password was not able to be acquired. 

07021 The character string length of the password exceeded the limitation. The 

maximum length is made effective. 

07030 The IP address was not able to be acquired. 

07031 The character string length of the IP address exceeded the limitation. The 

maximum length is made effective.. 

07040 The authentication type was not able to be acquired. 

07041 The character string length of the authentication type exceeded the limitation. 

The maximum is made effective. 

07500 Session not started. 

07510 Unable to start a session because COBW3_PUT_HTML or COBW3_PUT_TEXT 

already invoked. 

07520 Unable to end a session because COBW3_PUT_HTML or COBW3_PUT_TEXT 

already invoked. 

07558 Unable to start the timeout monitoring. 

07562 Failure in the timeout monitoring for some reason. 

07566 Failure in interrupting the timeout monitoring. 

07570 Unable to prepare for the timeout monitoring for some reason. Unable to start 

a session. 

07580 Unable to interrupt the timeout processing. 

07584 Incorrect session ID got from Cookie data. 

07588 Failure in getting the session information management area. 

07590 Failure in executing the timeout monitoring. 

07600 Session already started. 

07602 Unable to start a session because the timeout time is specified as 0. 

07604 Value exceeding the restriction specified for the timeout time. The processing 

is continued assuming that the maximum length is specified. 

07606 Unable to start a session because an invalid value is specified in the session 

data type. 

07608 Unable to start a session because of a failure in creating Cookie data for the 

session. 

07610 Unable to register session data because 0 was specified for the session data 

size.


07614 Value exceeding the restriction specified for the session data size. The 

processing is continued assuming that the maximum length is specified. 

07618 Incorrect object specified for the session data. 

07650 Unable to get session data because a mismatch exists between the specified 

and registered session data sizes. 

07660 Unable to get session data because a value other than null is set in the 

session data. 

07670 No session data registered. 

07680 Unable to change the timeout time because 0 was specified for the timeout 

time. 

08004 A negative value was specified for COBW3-HEADER-NAME-LENGTH. The 


08005 The script-name could not be acquired. 

08006 A value was specified that exceeded the limit for COBW3-HEADER-NAME- 

LENGTH. The processing continues assuming the maximum length was 

specified. 

08008 COBW3-HEADER-NAME is not specified. 

08010 Failed to acquire the HTTP header. 

08020 The length of COBW3_HEADER_VALUE exceeds the limit. The string is 

truncated to the supported length. 

08024 The HTTP header specified for COBW3_HEADER_NAME could not be found. 

08030 The character string length of the script-name exceeds the limit. The 

maximum length is used. 

08500 COBW3_PUT_HTML or COBW3_PUT_TEXT has already been called. Operation 

to cookie is invalid. 

08510 The cookie name is not specified. Set the cookie name. 

08512 A negative value was specified for the string length of the cookie name. The 


08514 A value was specified that exceeded the limit for the string length of the 

cookie name. The processing continues assuming the maximum length was 

specified. 

08520 The cookie value is not specified. Set the cookie value. 

08522 A negative value was specified for the string length of the cookie value. The 


08524 A value was specified that exceeded the limit for the string length of the 

cookie value. The processing continues assuming the maximum length was 

specified. 

08530 Failed to change the specified cookie data because it was not registered. 

08532 The specified cookie name has already been registered. The old cookie data 

remains effective. 

08540 A date before Oct 15, 1582 is not valid as a cookie period. The period is 

assumed not to have been specified. 

08541 The year for the cookie period is not specified correctly. The period is 


08542 The month for the cookie period is not specified correctly. The period is 


08543 The day for the cookie period is not specified correctly. The period is 

assumed not to have been specified.


08544 The hour for the cookie period is not specified correctly. The period is 


08545 The minute for the cookie period is not specified correctly. The period is 


08546 The second for the cookie period is not specified correctly. The period is 


08550 An invalid value was specified for the cookie security. The security is assumed 

not to have been specified. 

08560 An invalid value was specified for the cookie registration type. The 

registration type is assumed not to have been specified. 

08570 Failed in registration because the registration work area for the cookie data 

was insufficient. Please register again after calling COBW3 _INIT_COOKIE to 

initialize conversion information. 

08580 Failed to encode Cookie data. 

08610 Failed to delete the specified cookie data because it was not registered. 

08620 Failed to delete the specified cookie data. 

08710 An invalid value was specified for the initialization type of cookie information. 

The initialization type is assumed not to have been specified. 

08720 Failed in initialization of the request data by cookie information because the 

registration work area for the cookie information was insufficient. 

08810 The length of the cookie value exceeded the limit. The string is truncated to 

the supported length. 

08820 Cookie data was not sent from the client. 

09001 The correct value is not specified for COBW3_REQUEST_INFO_TYPE. 

09010 Failed to acquire the request. 

09020 The length of COBW3_REQUEST_INFO exceeded the limit. The string is 

truncated to the supported length. 

09500 COBW3_CNV_SET can't be used in the Unicode environment. 

09501 COBW3_CNV_DEL can't be used in the Unicode environment. 

09502 COBW3_NAME can't be used in the Unicode environment. 

09504 COBW3_VALUE can't be used in the Unicode environment. 

09520 This subroutine can't be used in the ASCII environment. 

20000 Failed to load the COBOL application. 

20001 The specified environment setting file does not exist. 

20002 No COBOL application to be executed is specified. 

20003 Failed to acquire the start address of the COBOL application processing to be 

executed. 

20004 An error of unknown origin occurs in the director. 

20005 Environment setting ends abnormally in the director. 

20006 Failed in memory allocation. 

20007 Environment setting descriptions are erroneous. 

20008 The environment setting file name is incorrect. 

20009 No COBOL application to be freed is specified. 

21000 COBW3-SAF-CONTEXT is not set.


21100 No character string is set in COBW3-SAF-PARM-NAME or COBW3-SAF-PARM- 

NAMEN. 

21102 A negative value is set in COBW3-SAF-PARM-NAME-LENGTH. The Web 

application regards the value as 0 and continues processing. 

21104 A value over the limit is set in COBW3-SAF-PARM-NAME-LENGTH. The Web 

application regards the value as the maximum value and continues 

processing. 

21106 COBW3-SAF-PARM-NAME could not be found. 

21110 Failed to acquire COBW3-SAF-PARM-VALUE. 

21112 The length of COBW3-SAF-PARM-VALUE exceeds the limit. The length up to 

the maximum length is valid. 

21210 Failed to acquire COBW3-SAF-BASENAME. 

21212 The length of COBW3-SAF-BASENAME exceeds the limit. The length up to the 

maximum length is valid. 

99999 Can’t open message catalog.

112 Appendix B. Error Recovery Processing

Appendix C. Architecture of a NetCOBOL SAF 

Application 

Commodity subscription 

screen 

Unit price 200 

A 1 


B 3 


C 4 

Submit Cancel 

Confirmation screen 

Application data has been 

registered. 

Name Quantity Sum 

A 1 200 

B 3 900 

C 4 400 

Return 

NES 


Director 


PROGRAM-ID. SAFMAIN01. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 


COPY COBW3. 

: 






* 


*Acquisition of data 

MOVE “PRICEA” TO COBW3-SEARCH-DATA. 

CALL “COBW3_GET_VALUE” USING COBW3. 

: 

*Registration of data 

MOVE “Quant i t y1” TO COBW3- CNV- NAME. 

MOVE O-QUANTITY1 TO COBW3-CNV-VALUE. 

CALL “COBW3_SET_CNV” USING COBW3. 

: 

*Setting path of result page 

SET COBW3-PHYSICAL-PATH TO TRUE. 


MOVE SPACE TO COBW3-HTML-FILENAME.. 

MOVE PATHNAME (1:PATHSIZE) TO 

COBW3-HTML-FILENAME. 

COMPUTE COPYSTARTPOS = PATHSIZE + 1. 

MOVE "/" TO 

COBW3-HTML-FILENAME (COPYSTARTPOS : 1). 

COMPUTE COPYSTARTPOS = COPYSTARTPOS+1. 

COMPUTE LEFTLENGTH = 256 – COPYSTARTPOS. 

MOVE HTMLFILENAME TO 

COBW3-HTML-FILENAME (COPYSTARTPOS : 256). 

* 

CALL "COBW3_PUT_HTML" USING COBW3. 

* 


* 

EXIT PROGRAM. 

… 

Application data has been 

registered. 

 

 

Name 

Quantity 

Sum 

 

 

A 

//COBOL//Quantity1//COBOL// 

//COBOL//Sum1//COBOL// 

114 Appendix C. Architecture of a NetCOBOL SAF Application

Appendix D. CGI To SAF Subroutines 

Conversion Guide 

The following describes how to convert Web applications using NetCOBOL CGI 

subroutines into Web applications using NetCOBOL SAF subroutines.

116 Appendix D. CGI To SAF Subroutines Conversion Guide 

Conversion from CGI to SAF 

In principle, NetCOBOL SAF subroutines (hereafter referred to as SAF applications) 

guarantee upward compatibility in source for COBOL CGI applications (hereafter 

referred to as CGI applications). Therefore, it is easy to modify Web applications 

created using CGI subroutines into Web applications using SAF subroutines. 

However, some modifications in the programs, compilations, and the linking methods 

are required, since the SAF subroutines have their own unique functions. This 

chapter describes the matters that require attention for the conversion from CGI to 

SAF. 

First, the table below shows the difference between Web applications created using 

CGI subroutines and Web applications using SAF subroutines. 

No. Item CGI applications SAF applications 

1 Application form Main program (EXE) Subprogram (DLL) 

2 Unit of execution Process Thread 

3 Server interface area Unnecessary Inevitable 

4 Environment variable operation Arbitrary Restricted 

5 CGI environment variable Enabled using supplied Enabled using supplied 

operation 

subroutines or 

DISPLAY/ACCEPT 

statements. 

subroutines only. 

To implement a conversion from CGI to SAF, the above-noted items must be 

modified. Details of these modifications are described in the following chapters. 

The subroutines shown below only work in an environment where Web applications 

run in the ASCII code system, though they are included in the supplied NetCOBOL 

SAF subroutines for the sake of compatibility. 

We recommend implementing corrections for the substitute subroutines, when 

performing a conversion from CGI to SAF.

Application Form 

Appendix D. CGI To SAF Subroutines Conversion Guide 117 

Old Subroutine name New Substitute subroutine name 

COBW3_NAME 

COBW3_GET_VALUE 

COBW3_GET_VALUE_XX 

COBW3_GET_VALUE_NX 

COBW3_GET_VALUE_XN 


COBW3_VALUE COBW3_CHECK_VALUE 

COBW3_CHECK_VALUE_X 


COBW3_CNV_SET COBW3_SET_CNV 

COBW3_SET_CNV_XX 

COBW3_SET_CNV_NX 

COBW3_SET_CNV_XN 


COBW3_CNV_DEL COBW3_DEL_CNV 

COBW3_DEL_CNV_X 

COBW3_DEL_CNV_N 

COBW3_CNV_INIT COBW3_INIT_CNV 

CGI applications and SAF applications have different executable formats. CGI 

applications execute as a main EXE file, whereas SAF applications execute as 

subroutine in .DLL files. Thus, it is necessary to make alterations in the following 

manner: 

• Descriptions of the Web applications started on the Web page for invoking 

applications 

• Compilation and linking methods 

Web Pages for Invoking Applications 

Change the extension “.EXE” of the Web applications on the invoking Web page into 

the extension (MIME type) used by the applications on NES. Before changing the 

extension, it is necessary to correct the obj.conf file and to register the MIME type. 

For details, refer to the Chapter2 or Chapter3. 

For example, a CGI application "CGI.EXE" and a SAF application "SAF.DLL" should be 

changed as shown below. 

Web page for invoking the CGI applications 

 

... 


Web page for invoking applications modified for SAF applications 

 

... 

 

Note: NES checks the extensions to identify applications. Thus, each application 

name need not be identical to the .DLL name, but will be the name of extension 

(MIME type) registered on NES. 

Compilation and Linking Methods 

Compilation Method 

In the case of CGI applications, there are no particular options for compiling 

programs. The only exception is the compilation option "MAIN", which the user has 

to set in the main program. On the contrary, the user must not set the compilation 

option "MAIN" in a SAF routine because each SAF application must be created in 

a.DLL format. In addition, SAF applications require the compilation option shown 

below. For details of the compilation option, refer to the "NetCOBOL User's Guide." 

• THREAD (MULTI) 

SAF applications are designed for multi-threaded operation. Set the compilation 

option THREAD (MULTI) in every source program. 

Linking Method 

In CGI applications, object files are linked to make .EXE files as shown below. 

LINK Main-program.obj F3BICIMP.lib LIBC.lib F3BICWSR.lib /OUT: 

Execution-format-name.exe 

SAF applications, however, must be created in .DLL format. In addition, linked the 

import library are different from CGI application program as follows. 

Unit of Execution 

LINK /DLL Initial-program.obj Work-program.obj End-program.obj 

F3BICBDM.obj F3BINSRT.lib F3BICIMP.lib KERNEL32.lib LIBC.LIB 

/OUT:Execution-format-name.dll /ENTRY:COBDMAIN 

Changing CGI applications into SAF applications means changing process-based 

applications into thread-based applications. The user should pay attention to the 

following: 

• Compilation method 

• Accessing common resources

Compilation Method 


It is necessary to set the compilation option THREAD (MULTI) for creating multithread 

objects. 

Accessing Common Resources 

A CGI application runs as one execution thread (single thread) in a dedicated process 

of the CGI application itself. Thus, there are no resources shared by several threads 

in a single process. 

A SAF application runs as several threads (multi-threads) within the process of NES 

itself. Therefore, several threads may share resources. 

It is necessary to control synchronization in order to prevent competition when SAF 

applications share common resources. Two types of synchronization controls are 

available for resource sharing: Automatic synchronization control by the COBOL runtime 

system, and synchronization control conducted by the SAF application itself 

using the "thread synchronization control subroutine" supplied by COBOL. 

For details, refer to the following sections in Chapter 24, Multithread Programs in the 

"NetCOBOL User’s Guide." 

• Resource Sharing among Threads 

• Thread Synchronization Control Subroutine 

Server Interface Area 

Users of CGI applications need not pay particular attention to the interface with the 

WWW server, with the exception of the environment variables. An SAF application is 

called by the NetCOBOL SAF director initiated by NES and receives an interface 

(parameter) area for transferring data with the NetCOBOL SAF director. Thus, it is 

necessary to modify the LINKAGE SECTION and PROCEDURE DIVISION when 

changing a CGI application into a SAF application. In addition, it is necessary to set 

the address of the interface area into COBW3, which is the interface with SAF 

subroutines. For example: 

Contents of the CGI application 


COPY COBW3. 


MOVE LOW-VALUE TO COBW3.


Modified contents of the SAF application 


COPY COBW3. 

* COPY COBW3SAF. 





* MOVE LOW-VALUE TO COBW3SAF 


* SET COBW3-SAF-CONTEXT TO SAFCTX. 

Note: Delete the comment indicators when using a SAF specific function. 

Environment Variable Operations 

An environment variable block is assigned to each process. Since CGI applications 

run as separate processes, each is responsible for its own environment variables and 

it will not interfere with other processes. However, an SAF application runs as 

several threads in NES process. Thus, the SAF application may affect NES or other 

applications if it modifies environment variables. Thus, it is necessary to make 

alterations in order to remove the use of environment variables when converting an 

application from CGI to SAF. 

It is not safe to assume that the current folder is unchanged when a SAF application 

is called. Thus, the user must pay attention to functions that use the current folder 

in the background, for example, a file operation specifying a relative path from the 

current folder. To avoid trouble, the following methods are recommended: 

• Specifying a file in an absolute path 


MOVE "RESPONSE.HTM" TO COBW3-HTML-FILENAME. 



MOVE "C:\COBOL\SAF\RESPONSE.HTM" TO COBW3-HTML-FILENAME. 


• Specifying a file position using the physical path corresponding to the virtual path 

Use COBW3_GET_REQUEST_INFO to acquire the physical path corresponding to 

the virtual path. 



CALL "COBW3_PUT_HTML" USING COBW3.

Modified contents of a SAF application 


SET COBW3-PHYSICALPATH TO TRUE 


MOVE COBW3-REQUEST-INFO TO COBW3-HTML-FILENAME. 

MOVE "\RESPONSE.HTM" TO 

COBW3-HTML-FILENAME(COBW3-REQUEST-INFO-LENGTH + 1:13). 


• Using a value specified by the SAF director 

It is possible to acquire a set of a name and value specified with 

COBOL_Perform in the obj.conf file, using COBW3_SAF_GET_PARM etc. 

Then, append path which Web application uses and the file name of the 

required file. 





MOVE "APPPATH" TO COBW3-SAF-PARM-NAME. 

CALL "COBW3_SAF_GET_PARAM" USING COBW3 

IF COBW3-SAF-PARM-FLAG-EXIST THEN 

MOVE COBW3-SAF-PARM-VALUE TO COBW3-HTML-FILENAME 

MOVE "\RESPONSE.HTM" TO 

COBW3-HTML-FILNAME(COBW3-SAF-PARM-VALUE-LENGTH + 1:13) 

ELSE 

MOVE "Default-path-name\RESPONSE.HTM" TO COBW3-HTML-FILENAME 

END-IF. 

CALLL "COBW3_PUT_HTML" USING COBW3. 

Setting of the SAF director in the obj.conf file 

Service method=(GET|POST) type="magnus-internal/cob-app" 

sev="0" APPPATH="C:/COBAPL/APP" 

File specification in the run-time initialization file (COBOL85.CBR) is related to this. 

SAF applications cannot use relative paths, whereas either an absolute path or a 

relative path may be set for a CGI application. No substitute method is available, so 

the run-time initialization file must be modified to allow absolute paths to be set. 

COBOL85.CBR of the CGI application 

[Program name] 

Access-name=SEQFILE.DAT 

COBOL85.CBR modified for the SAF application 

[Program name] 

Access-name=C:\COBOL\SAF\SEQFILE.DAT


Operations of CGI Environment Variables 

A CGI application can reference the "CGI environment variables" using the 

environment variable operation function of COBOL. On the contrary, an SAF 

application cannot reference them. Thus, it uses three subroutines shown below: 

• COBW3_RECEIVE _HEADER 

This subroutine acquires an HTTP header. 

• COBW3_GET_REQUEST_INFO 

This subroutine acquires various types of information related to a request. 

• COBW3_GET_AUTHORIZE 

This subroutine acquires authorization information. 

In addition, a CGI application can set or reference Cookie data using the 

environment variable operation function of COBOL. An SAF application cannot 

handle Cookie data using the environment variable operation function of COBOL. 

Use the subroutines for handling Cookie data shown below. 

• COBW3_SET_COOKIE, etc. 

This subroutine registers Cookie data. 

• COBW3_DEL_COOKIE, etc. 

This subroutine deletes registered Cookie data. 

• COBW3_INIT_COOKIE 

This subroutine initializes Cookie data to be sent to the client. 

• COBW3_GET_COOKIE, etc. 

This subroutine acquires Cookie data contained in a request. 

For example, modify processing for acquiring information from the HTTP header as 

shown below. 


DISPLAY "HTTP_USER_AGENT” UPON Environment-variable-name. 

ACCEPT Browser-information FROM Value-of-the-environment-variable 

ON EXCEPTION 

MOVE "Error" TO Browser-information 

END-ACCEPT. 


MOVE "User-agent" TO COBW3-HEADER-NAME. 

CALL "COBW3_RECEIVE_HEADER" USING COBW3. 

IF COBW3-STATUS = ZERO THEN 

MOVE COBW3-HEADER-VALUE TO Browser-information 

ELSE 

MOVE "Error" TO Browser-information 

END-IF.

Modify Cookie operation as shown below. 





COPY COBW3. 

01 COOKIEDATA. 

02 PIC X(19) VALUE "Sample+cookie+data=". 

02 COOKIEVALUE PIC X(32). 


: 

DISPLAY "HTTP_COOKIE" UPON Environment-variable-name. 

ACCEPT COOKIEVALUE FROM Value-of-the-environment-variable 

ON EXCEPTION 

MOVE "Error" TO COOKIEVALUE 

END-ACCEPT. 




COPY COBW3. 

01 COOKIEVALUE PIC X(32). 

: 


: 

MOVE "Sample cookie data" TO COBW3-COOKIE-NAME. 

CALL "COBW3_GET_COOKIE" USING COBW3. 

IF COBW3-STATUS = ZERO THEN 

MOVE COBW3-COOKIE-VALUE TO COOKIEVALUE 

ELSE 

MOVE "Error" TO COOKIEVALUE 

END-IF. 

Note: The user must execute URL encoding and URL decoding of Cookie data when 

handling the Cookie data by means of environment variable operation. To avoid 

such encoding and decoding, use Cookie data consisting of alphanumeric characters 

only. 

For example, an en-size space becomes a "+" as a result of URL encoding.

124 Appendix D. CGI To SAF Subroutines Conversion Guide

NetCOBOL for SPARC Architecture SAF Subroutines User's Guide

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?