Server Guide

Accessing files from Smalltalk

To access and modify files that are either defined in the resource association file for workstation simulation or are defined as DD names for OS/390 processing, you need to create an instance of the type of file you are accessing. Class methods in both SrvVsamFileDescriptor and SrvBasicFileDescriptor enable your program to retrieve the correct file or data set. Using the proper instance methods, your program can then modify the data found in the specified file. Once the file is accessed, you can modify the data using classes and methods from IBM Smalltalk. These classes and methods are documented in IBM Smalltalk Programmer's Reference.

The class methods you will use to access either VSAM, PDS, or sequential files are open:mode: for sequential or VSAM files and open:member:mode: for PDS members. These methods require you to specify the file descriptor and the mode of access requested. For PDS members, you must also specify the member you want to open. The file will be opened, regardless of whether you intend to read or write, in binary format. When writing an OS/390 Native application that accesses PDS members, the simulation system on the workstation allows you to open more than one PDS member for write from the same file directory. When the application is ported to OS/390, it will fail, as only one PDS member can be opened for write from the same data set. However, it will work properly for PDSE members.

Note:If you plan to use Smalltalk methods to read and write from an opened file, then the file must be opened using Smalltalk methods. You cannot, for example, open a file using a COBOL application and call a Smalltalk application to read from the file.
The possible choices for the mode: portion of the method are as follows:

APPEND
The file is to be opened for writing only. For sequential files on a workstation, if the file exists, records will be appended to the contents of the file; if the file does not exist, it will be created. For sequential files on OS/390, the file must exist. This is not a valid parameter for PDS members or VSAM files.

READ
The file is to be opened for reading only, starting from the beginning of the file.

WRITE
The file is to be opened for writing only. If the file exists, the contents are destroyed, and the records will be written starting at the beginning of the file. For PDS members or sequential files on a workstation, if the file your application is attempting to access does not exist, it will be created. For sequential files on OS/390, the file must exist. For PDS members on OS/390, the file will be created. For VSAM files, the file must exist; that is, VSAM files must be pre-allocated, both on the workstation and on OS/390. Also, VSAM opens the file for reading and writing.

Reading a record from an accessed file

Depending on the file type of the file you are accessing, you can read records from that file using different methods.

For VSAM files, you will be using the methods included with SrvVsamFileDescriptor. To read a record from a VSAM file, use any of the read... methods:

Each of these methods returns the record read (as a ByteArray) or, in the case of an error, an SrvFileError object. Before reading a record from a KSDS or RRDS file, you must position the file pointer by using a startBrowse... method. For an ESDS file, you can open the file and use the readNext method to read the first record in the file.

When the read request is complete, you can obtain the relative id field of the file using the rid method. For a KSDS file, rid answers the key of the record read; for an RRDS file, rid answers the relative record number (RRN) of the record read; for an ESDS file, rid answers the relative byte address (RBA) of the record read. The following example illustrates reading a record from a KSDS VSAM file:

| record file key |
 
"Open the file for reading only"
file := SrvVsamFileDescriptor open: 'FILEV' mode: 'READ'.
 
 "Set the file pointer at the first record"
file startBrowseAt: ' '.
 
"Read the first record"
record := file readNext.
 
"Test for error"
record isSrvFileError
   ifTrue: [Transcript cr; show: 'Error code: ', record rc printString]
   ifFalse: [
                  "Print the record, using VsamRecord, which is a COBOL
                   structure parsed into a Smalltalk object and a subclass
                   of OsPtr and save the rid"
                 Transcript cr; show: (VsamRecord reference: record) printString.
                 key := file rid].
 
"Close the file"
file close.

For PDS members and sequential files, you will be using the methods included with SrvBasicFileDescriptor. To read a record from a PDS member or sequential file, use the read method, which returns the record read (as a ByteArray) or, in the case of an error, an SrvFileError object. When a PDS member or sequential file is opened for reading, the file position is always at the beginning of the file; therefore, your program will begin reading records from the beginning of the file. There is no browse mechanism for use with PDS member or sequential file records. The following example illustrates reading all the records from a sequential file until the end of file is encountered:

| record file |
 
"Open the file for reading only"
file := SrvBasicFileDescriptor open: 'FILEB' mode: 'READ'.
 
"Read the first record"
record := file read.
 
"Loop until end of file or error encountered"
[record isSrvFileError]
   whileFalse: [
      "Print the record, using BasicRecord, which is a C structure parsed
       into a Smalltalk object and a subclass of OsPtr"
      Transcript cr; show: (BasicRecord reference: record) printString.
     
      "Read the next record"
      record := file read.].
 
"Test for end of file"
record atEnd
   ifTrue: [Transcript cr; show: 'End of file reached'.]
   ifFalse: [Transcript cr; show: 'Error code: ', record rc printString].
 
"Close the file"
file close.

Writing a record to an accessed file

Depending on the file type of the file you are accessing, you can write records to that file using different methods.

For VSAM files, you will be using the methods included with SrvVsamFileDescriptor. To write a record to a VSAM file, use either the write:at: method, which writes your record at the relative id field you specify, or the write: method, which writes your record to a pre-determined location. When writing to KSDS or ESDS files, it is best to use the write: method; for RRDS files, use the write:at: method, as you must supply a relative record number (RRN).

The record can be one of the following objects:

The relative id field contains one of the following:

Both the write: and write:at: methods return an instance of SrvVsamFileDescriptor or, in the case of an error, an SrvFileError object.

When the write request is complete, you can obtain the relative id field of the file using the rid method. For a KSDS file, rid answers the key of the record written; for an RRDS file, rid answers the RRN of the record written; for an ESDS file, rid answers the RBA of the record written.

The following example illustrates opening a file to append a record to an existing ESDS VSAM file:

| record file rba request |
 
"Open the ESDS file for reading and writing"
file := SrvVsamFileDescriptor open: 'FILEE' mode: 'WRITE'.
 
"Create the record to write as an instance of EsdsRecord, which is
 a COBOL structure parsed into a Smalltalk object and a subclass of
 OsPtr"
record := EsdsRecord new.
record
     name: 'John Doe';
     employeeNumber: '123456';
     weeklySalary: 1000;
     shift: 'First'.
 
"Write the record"
request := file write: record.
 
"Test for error"
request isSrvFileError
   ifTrue: [Transcript cr; show: 'Write error code: ', rba rc printString]
 
"Save the RBA"
rba := file rid.
 
"Close the file"
file close.

For PDS members and sequential files, you will be using the methods included with SrvBasicFileDescriptor. To write a record to a PDS member or sequential file, use the write: method, which returns an instance of SrvBasicFileDescriptor or, in the case of an error, an SrvFileError object.

The record being written can be one of the following:

The following example illustrates opening a PDS member in write mode, which destroys the contents of the file, and writing a record:

| record file request |
 
"Open the file for writing only"
file := SrvBasicFileDescriptor open: 'PDSFILE' 
                               member: 'MEMBER01' 
                               mode: 'WRITE'.
 
"Create the record to write as an instance of PdsRecord, which is
 a COBOL structure parsed into a Smalltalk object and a subclass of
 OsPtr"
record := PdsRecord new.
record
    name: 'Jane Doe';
    employeeNumber: '987654';
    date: Date today printString.
 
"Write the record"
request := file write: record.
 
"Test for an error"
request isSrvFileError
   ifTrue: [Transcript cr; show: 'Error on write: ', request rc printString].
 
"Close the file"
file close.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]