The Datastore URL

There are a number of utilities and library routines that allow you to interact with data files and folders hosted in a database. In order to reference those files and folders within a datastore, you need to use a specific URL, as described below:

sql://<server-name>/<datastore-name>/<file-name>[?<file-attributes>]     *> file url
sql://<server-name>/<datastore-name>?type=folder;[folder=/<folder-name>] *> folder url

where:

server-name
The name of the server entry in the database configuration file. When "(local)" or "localhost" is specified as the server name, it is replaced at run time by the name of the machine running the process using it.
datastore-name
The name of the datastore.
file-name
The name of the data file.
file-attributes
Attributes for the data file, such as its type and its location in the datastore:
Attribute Values Example Description
type
  • blob
  • folder
  • lseq
  • rrds
  • seq
  • type=blob
  • type=folder
  • type=lseq
  • type=rrds
  • type=seq
File type. This only needs to be specified when deploying files into the database that do not have file headers
reclen <min[,max]>
  • type=lseq;reclen=0,80
  • type=seq;reclen=0,80
  • type=rrds;reclen=80
  • type=seq;reclen=80
Minimum and maximum max record lengths of variable-length sequential files, or the record length of fixed-length sequential or RRDS files. This only needs to be specified when deploying files into the database that do not have file headers
recterm
  • windows
  • linux
  • unix
  • recterm=windows
  • recterm=linux
  • recterm=unix
The type of record terminator the file has. Used primarily for RRDS files, and only required for files that have been created on a platform different to the one on which it is currently being deployed
folder <folder-name>
  • folder=/MyFolder
  • folder=/MyFolder/SubFolder
Folder name. If a folder name is not explicitly specified, the root folder is assumed (i.e. folder=/)
Note: On the command line, you can also run dbfhdeploy.exe -urlhelp to view syntax help.
MSSQL users: If your database instance is configured with a case-sensitive collating sequence, you must specify the files and folders in the dbfhdeploy command accordingly.

Using environment variables in the URL[4]

You can use environment variables within the SQL URL, which can be specified in one of two formats:

  • $name - where the variable name is terminated by the next punctuation character or by the end of string.

    For example: sql://$MYSERVER/$MYDATASTORE/myfile.dat

  • ${name} - where the variable name is enclosed in the brackets.

    For example: sql://${MYSERVER}/${MYDATASTORE}/myfile.dat

Restriction: The second format is not supported if you are specifying SQL URLs within an Enterprise Server environment, for example, when defining the JES catalog location or file allocation folder.

Examples

  • The following example references a file (my.dat) held in the JCLTEST datastore housed in a database instance on the swt-bto host:
    sql://swt-bto/JCLTEST/my.dat
  • The following example references another file (another.dat) held in the MyData folder in the datastore indicated by the JCLDATASTORE environment variable:
    sql://swt-bto/$JCLDATASTORE/another.dat?folder=/MyData
  • The following example references a sequential file (newseq.dat) held in the MySeqData folder in the SEQDATA datastore located in the database instance held on the machine indicated by the ${MYSVR} environment variable:
    sql://${MYSVR}/SEQDATA/newseq.dat?folder=/MySeqData;type=seq;reclen=0,80