Commands

Heel! Sit! Fetch! Those are three commands you are used to giving (or trying to give) your dog. The computer works in similar ways--except that instead of those particular words, it listens to CS.GetActiveRecord, CS.SaveRecord, and CS.GetField. Also like a dog, if you give the computer a command it doesn't understand, it will sit there and do its best impression of a quizzical look, much to the aggravation of the person giving the commands.

You've already been introduced to a few commands in earlier lessons-- variable definitions and CS.AddField among them. Let's start with a simple macro:

  Sub Main
    Dim CS as Object
    Set CS = CreateObject("Connex.Client")
    bool = CS.AddField(99, "949  Some note here.")
  End Sub

Recap: What this does is set up the "CS" shortcut, verify that there is an open record to act upon, and then add a field after any existing 949 fields, with the contents "949  Some note here.")

Many commands, CS.AddField among them, allow you to substitute variables for certain sections of the command. Any command that needs a whole number or some text can use an Integer variable or a String variable instead; it's only a matter of replacing the numeric constants (such as 1) and string constants (such as "949  Some note here") with numeric variables and string variables. For example, another way of achieving an identical via with a somewhat different method is to do this:

  Sub Main
    Dim CS as Object
    Set CS = CreateObject("CatME.Application")

    x% = 99
    FieldNum$ = "949"
    Indicators$ = "  "
    FieldContents$ = "Some note here."
    FullField$ = FieldNum$ & Indicators$ & FieldContents$

    CS.GetActiveRecord
    bool = CS.AddField(x%, FullField$)
  End Sub

In this particular example, it's actually easier to just use the plain number and text. However, there are times when knowing how to use variables with this command may come in very handy.

Ever wanted to pop up a window with a message for the user (such as "Macro has finished") and an "Ok" Button, but couldn't figure out the Dialog Box commands? If that's all you need it to do, there's an easy method to do just that--the Message Box.

  MsgBox "Hello World"

As you can see, in its basic form the command is fairly straightforward; all you need to supply is the text to be displayed, and the computer takes care of the rest. If you use variable strings instead of a string constant (that is, instead of plain text in quotes), things can get quite interesting:

  sub main
    a$ = "Hello"
    b$ = " World"
    c$ = " Cup Soccer"
    d$ = ", I must be going"
    e$ = a$ & b$
    MsgBox a$ & b$
    MsgBox e$
    MsgBox a$ & " Dolly"
    MsgBox b$ & c$
    MsgBox a$ & d$
  end sub

After a while, you may find the command CS.GetField to be worth its weight in gold. More than that, actually, since it doesn't weigh all that much. You will usually see the command in the form:

  bool = CS.GetField("650", 1, Text$)

The way it works is this: The command looks at the current screen, finds the first instance of the specified tag (using 2 would get the second instance, and so forth), gets all the text in that line, and stores it in Text$. It is important to note that CS.GetField always formats the data with no spaces between the tag and the indicators, and the indicators and the field's data. Thus, the first three characters are always the tag number, the fourth and fifth characters are always the indicators (which may be spaces), and the sixth and further characters are always the field data.

CS.SetField works in the reverse as CS.GetField; it enters data back into the record. Also, another way of thinking of it is that, whereas CS.AddField is an "insert" command, CS.SetField is an "overstrike" command.

  Text$ = "650 0Cats."
  bool = CS.SetField(1, Text$)

This macro fragment replaces the first instance of the specified tag number with the contents of Text$. You must include the tag number in quotes or as a string variable, and also include it as the first three characters of the text to input into the record followed immediately by two indicators (using spaces if there aren't any), followed immediately by the field data.

Connexion also includes alternate versions of AddField, GetField, and SetField, for those instances when you want to edit any or every line in a record, not necessarily only those with a single specific tag. These can be useful when similar data can be found in various tags (such as 6XX fields, 504 vs. 500 for index information, and so forth).

  bool = CS.AddFieldLine(1, Text$)

This macro fragment adds a new field as the very first field in the record. The data in Text$ must be formatted in the same way as for CS.AddField. Using a very high field number (such as 99 or 999) will ensure that the new field is added as the last line in a record.

  bool = CS.GetFieldLine(1, Text$)

This macro fragment reads in the very first field in the record, regardless of what tag it has, and stores it in Text$. It uses the same formatting of tag, indicators, and data as CS.GetField.

  bool = CS.SetFieldLine(1, Text$)

This macro fragment writes the data stored in Text$ into the record, using it to replace the data in the very first field in the record, regardless of what tag it has. The data in Text$ must be formatted in the same way as for CS.SetField.

While you're thinking about getting and setting data, there are two more commands you should know about: CS.GetFixedField and CS.SetFixedField.

  bool = CS.GetFixedField("Lang", LangCode$)
  bool = CS.SetFixedField("Lang", "eng")

If you want to delete a line, and know the line number, use CS.DeleteField. The following example deletes the first 650 field of the record, and shows how to use a variable to do so.

  FieldNum$ = "650"
  bool = CS.DeleteField(FieldNum$, 1)

Like the other field-related commands, Connexion also includes a version of DeleteField that looks at the absolute field number (first field, second field, etc.) rather than only the first, second, etc. field with a specific tag.

  bool = CS.DeleteFieldLine(1)

Most of OCLC's record actions can also be automated with macros; these commands usually take the form of bool = CS.<command>, though there are some exceptions. Examples of such commands include:

  bool = CS.UpdateHoldings
  bool = CS.ProduceAndUpdateHoldings
  bool = CS.DeleteHoldings
  bool = CS.Export
  bool = CS.Print
  bool = CS.Reformat
  bool = CS.Lock
  bool = CS.ReplaceRecord
  bool = CS.ReleaseRecordLock
  bool = CS.DeleteRecord
  SaveFileNum% = CS.SaveOnline
  NumErrors% = CS.Validate(ErrorList$)

Using some of what you've learned, you can now write a macro that can add a field, alter the added field, display the old and new lines in a message box, then export and save the file to the online save file.

  Sub Main
    'Set up CS shortcut
    Dim CS As Object
    Set CS = CreateObject("Connex.Client")

    'Add a new 949 field to the record
    bool = CS.AddField(1, "949  ABCD")

    'Get the contents of the first 949
    bool = CS.GetField("949", 1, OldField$)

    'Set up the new field
    NewField$ = "949  DCBA"

    'Put the new field into the record
    bool = CS.SetField(1, NewField$)

    'Display the results in a message box
    MsgBox OldField$ + Chr(10) + "was replaced with" + Chr(10) + NewField$
    
    'Export the record
    bool = CS.Export

    'Save the record in the online save file
    bool = CS.SaveOnline
  End Sub

Pretty amazing!

Next time, more commands...