[Info-vax] Listeners in VMS Basic, was: Re: Integrity iLO Configuration?

[Arne Vajhøj]

On 7/1/2021 4:24 PM, Dave Froble wrote:
> On 7/1/2021 2:36 PM, Arne Vajhøj wrote:
>> On 7/1/2021 10:40 AM, Dave Froble wrote:
>>> As for Arne's example, whatever it does, it sure is not maintainable.
>>> If code is not maintainable, what good is it?
>>
>> It is an rtificial piece of code as it basically does a very
>> trivial operation (sum an array) 5 different ways and time them.
>>
>> But the basic elements should be relative easy
>> ]understandable by millions of developers.
>>
>> Basically it contains:
>> * Basic syntax
>> * OOP
>> * arrays
>> * calls
>> * basic thread usage
>> * basic thread pool usage
>> * fluent API syntax
>>
>> You noted the lack of comments, but there really should
>> only be a few explaining what the classes and methods do.
>> The rest is RTFM stuff.
> 
> All code should explain itself.  The manuals are there to define 
> specifics, such as the arguments in a QIO call.  But the program 
> comments should explain why the QIO is being called.

If necessary. yes.

> There wasn't even one comment in your example, to at least explain what 
> the code would attempt to do.  Making someone puzzle out such is not a 
> good practice.  Actually, it is a very bad practice.

I think it is very common practice for code written for usenet.

It would be bad practice for real code.

> Code should be maintainable.  To be such, there is no such thing as too 
> many comments.

I think there is.

> An example of how I write code.
> 
> at the top of a subprogram:
> 
>          !************************************************
>          !       This subprogram will set up TCP/IP sockets to allow
>          !       itself to connect to a service, send a message, and
>          !       receive a response.
>          !
>          !       The timeout AST is queued prior to any network
>          !       activity.  It's left on until the routine exits.
>          !       The concept is that the user doesn't really care
>          !       why the routine timed out.  The routine has a
>          !       specified amount of time to complete it's task,
>          !       and then the task is aborted.
>          !
>          !************************************************
> 
> useful information:
> 
>          ! Parameter list:
>          !
>          !       IP.ADR$         - IP address string
>          !       PORT%           - WORD port number
>          !       SEND.MSG$       - Message to send (max 4096 bytes)
>          !       RECV.MSG$       - Return message target (max 4096 bytes)
>          !       W%              - Seconds to wait for response
>          !       E$              - Error message
>          !       COMP.STAT%      - WORD Completion status
> 
> what you're going to do:
> 
>       !************************************************
>          !             Create Connection Socket
>          !************************************************
> 
>          SOCKOPT::PROTOCOL% = TCPIP$C_TCP                !  Socket 
> characteristi^
>          SOCKOPT::TYP$ = CHR$(TCPIP$C_STREAM)
>          SOCKOPT::AF$ = CHR$(TCPIP$C_AF_INET)
> 
>          Stat% = SYS$QIOW(       ,                       !  Event flag &
>                                  CH% By Value,           !  VMS channel &
>                                  IO$_SETMODE By Value,   !  Operation &
>                                  IOSB::Stat%,            !  I/O status 
> block &
>                                  ,                       !  AST routine &
>                                  ,                       !  AST parameter &
>                                  SOCKOPT::PROTOCOL%,     !  P1 &
>                                  ,                       !  P2 &
>                                  ,                       !  P3 &
>                                  ,                       !  P4 &
>                                  ,                       !  P5 &
>                                  )                       !  P6
> 
> you might notice the arguments on separate lines, to allow documentation 
> of each argument
> 
> you might also notice that I could have better explained the passing of 
> the item list by ref in the P1 argument
> 
> and of course the mandatory error testing:
> 
>          If      ( Stat% And SS$_NORMAL ) = 0%
>          Then    Call VMSERR( Stat% , E$ )
>                  E$ = "Unable to queue create connection socket - " + E$
>                  E% = -1%
>                  SaveStat% = Stat%
>                  GoTo Deassign_Channel
>          End If
> 
>          If      ( IOSB::Stat% And SS$_NORMAL ) = 0%
>          Then    Call VMSERR( IOSB::Stat% , E$ )
>                  E$ = "Unable to create connection socket - " + E$
>                  E% = -1%
>                  SaveStat% = IOSB::Stat%
>                  GoTo Deassign_Channel
>          End If
> 
> Things like the above are the minimum acceptable, to me, and, more would 
> be better.

Doing the entire thing in VB.NET would without comments look like:

     Public Class SocketComm
         Public Shared Function SendAndReceivce(host As String, port As 
Integer, request As String) As String
             Dim client As New TcpClient(host, port)
             Dim writer As New StreamWriter(client.GetStream())
             Dim reader As New StreamReader(client.GetStream())
             writer.Write(request)
             writer.Flush()
             Dim result As String = reader.ReadToEnd()
             reader.Close()
             writer.Close()
             client.Close()
             Return result
         End Function
     End Class

which is very close to self explainable.

But for a professional finish then I would add comment on class,
comment on method and an explanation of why Flush is needed:

     ''' <summary>
     ''' Class for simple socket communication - one request and one 
response.
     ''' </summary>
     Public Class SocketComm
         ''' <summary>
         ''' Send request and receive response.
         ''' </summary>
         ''' <param name="host">host name</param>
         ''' <param name="port">port number</param>
         ''' <param name="request">request</param>
         ''' <returns>response</returns>
         Public Shared Function SendAndReceivce(host As String, port As 
Integer, request As String) As String
             Dim client As New TcpClient(host, port)
             Dim writer As New StreamWriter(client.GetStream())
             Dim reader As New StreamReader(client.GetStream())
             writer.Write(request)
             writer.Flush() ' must flush or method will hang
             Dim result As String = reader.ReadToEnd()
             reader.Close()
             writer.Close()
             client.Close()
             Return result
         End Function
     End Class

I would not add comments on everything like:

     ''' <summary>
     ''' Class for simple socket communication - one request and one 
response.
     ''' </summary>
     Public Class SocketComm
         ''' <summary>
         ''' Send request and receive response.
         ''' </summary>
         ''' <param name="host">host name</param>
         ''' <param name="port">port number</param>
         ''' <param name="request">request</param>
         ''' <returns>response</returns>
         Public Shared Function SendAndReceivce(host As String, port As 
Integer, request As String) As String
             Dim client As New TcpClient(host, port) ' instantiate new 
TcpClient from host name and port number
             Dim writer As New StreamWriter(client.GetStream()) ' 
instantiate new StreadWriter from client stream
             Dim reader As New StreamReader(client.GetStream()) ' 
instantiate new StreadReader from client stream
             writer.Write(request) ' write request to streamwiter
             writer.Flush() ' flush stream writer
             Dim result As String = reader.ReadToEnd() ' read all of 
response from stream reader
             reader.Close() ' close stream reader
             writer.Close() ' close stream writer
             client.Close() ' close tcp client
             Return result ' return result
         End Function
     End Class

as all those comments does not provide any value - the information
written in English is already present in Basic.

But I am sure that there are more cases with SUS$QIOW where comments
are needed than with TcpClient.

Arne