# $language = "VBScript"
# $interface = "1.0"

' UseDescriptionFieldAsScriptArguments.vbs
'   Last Modified:
'     21 Feb, 2023
'       - Bring example into conformity with Python edition
'
'     11 Dec, 2011
'       - Initial revision
'
' Description:
'   Designed for use with SecureCRT 6.5 or later.
'
'   This script serves as an example of how to use the "Description" field of
'   the Session Options as arguments that can be read in from a logon script.
'   Since SecureCRT provides a unique field for "notes" and other generic
'   information, one can decide a way to use this mechanism to store arguments
'   that can be "passed" to a common (logon) script that is shared among
'   multiple sessions.  The behavior of the script can then be controlled based
'   on the value(s) stored in the "Description" field as described below.
'
' WARNING:
'   The "Description" field within a saved session's configuration is not
'   stored with any encryption or obfuscation of any kind. For example:
'      Z:"Description"=00000003
'       This is my description!
'       ARG: plain-text-value1
'       ARG: plain-text-value2
'   Alghough you could specify username or password information using the
'   method demonstrated in this script, it is not considered a security best
'   practice to save passwords with any mechanism.
'
' Usage:
'   - Specify arguments to your script as entries within the Description field
'     in the Connection category within the Session Options dialog.  Although
'     this could be done in many different ways, for this example, the choice
'     was to have a one argument per line.  This makes parsing arguments that
'     may or may not contain spaces more trivial.
'
'   - This script loads information from the "Description" field in session
'     options by making use of the Session.Config script object's GetOption()
'     method.  In the case of the "Description" option, an array of strings is
'     returned, and we simply iterate over that array looking for lines that
'     begin with "ARG:" and we treat everything to the right of that tag on a
'     single line as the value for that positional argument.  Here's an example
'     of a Description field that has both a description (ignored) as well as
'     arguments that can be used by a logon script with this code:
'
'        This is located in Marge's office on the 3rd floor of the Annex.
'        ARG: script_info_1
'        ARG: script_info_2
'

Dim g_vArgs
Dim g_nArgCount

Const ForReading = 1

'~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Function GetArgs()
    ' Function returns an array of all the arguments parsed from the session's
    ' Description field. The caller will check the size of the array returned
    ' for evidence of success/fail.

    vDescriptionLines = crt.Session.Config.GetOption("Description")

    ' Start with an empty value representing the lines which contain
    ' arguments
    strArgs = ""
    
    ' Read each line of the Description text one by one, looking for any
    ' lines which reflect the tag "ARG:". For any args found, add them to
    ' a string variable with each arg value delimited by a CRLF sequence.
    For Each strLine In vDescriptionLines
        strLine = Trim(strLine)

        ' Ignore empty lines and lines that don't start
        ' with "ARG:" within the Description field
        If Left(strLine, 4) = "ARG:" Then
            strArg = Trim(Mid(strLine, 5))
            If strArgs = "" Then
                strArgs = strArg
            Else
                strArgs = strArgs & vbcrlf & strArg
            End If
        End If
    Next
    
    ' Use the Split() method to convert our string into any array of args:
    GetArgs = Split(strArgs, vbcrlf)
End Function

'~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sub MsgBox(strText)
    ' Just a wrapper around simple MsgBox uses so that we get tible bars and
    ' ability to display more than 1024 characters "for free".
    crt.Dialog.MessageBox strText
End Sub


'~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sub ExMain()
    ' This script will only work with SecureCRT version 6.5 or later.
    vVersionElements = Split(crt.Version, ".")
    If Int(vVersionElements(0)) < 6 Then
        bVersionValid = False
    ElseIf Int(vVersionElements(0)) = 6 And Int(vVersionElements(1)) < 5 Then
        bVersionValid = False
    Else
        bVersionValid = True
    End If
    
    If Not bVersionValid Then
        MsgBox "This script works with SecureCRT 6.5 or later." & vbcrlf & _
               "The version you are running is " & crt.Version
        Exit Sub
    End If

    ' Populate the Arguments array and counter variable.
    g_vArgs = GetArgs()
    g_nArgCount = UBound(g_vArgs) + 1
    If g_nArgCount < 1 Then
        MsgBox _
            "No arguments found in this session's Description field:" & _
            vbcrlf & String(36, "=") & vbcrlf & _
            "Session Name: " & crt.Session.Path & vbcrlf & _
            String(36, "=") & vbcrlf & _
            "Description: " & vbcrlf & String(36, "=") & vbcrlf & _
            Join(crt.Session.Config.GetOption("Description"), vbcrlf)
        Exit Sub
    End If

    ' Use the arguments we discovered;
    ' simple example: display them in a dialog box.
    strArgsText = "Found " & g_nArgCount & " argument(s) in the " & _
        "Description field for this session:" & _
        vbcrlf & String(36, "=") & vbcrlf & _
        Join(g_vArgs, vbcrlf)

    MsgBox strArgsText

    'strFirstArg = g_vArgs(0)
    'strSecondArg = g_vArgs(1)
    '... and so on

End Sub

' Launch our main subroutine
ExMain